@smartkomm/plexus-cli 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,59 @@
+# 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
+
+# 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.
+- 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`.

package/dist/skill/references/users/change-login-email.md

@@ -0,0 +1,55 @@
+# Change a user's login e-mail
+
+**When to use:** an account's login address has to move — above all a made-up
+test account on a real, deliverable domain (`test100@<domain>.com`) that must go to a
+reserved one (`test100@<domain>.test`) so no mail can ever reach a stranger.
+
+## Prerequisites
+- A platform token with `_platform.users.manage` for the target env.
+- The account exists (`plexus-cli --env <env> users show <email>`).
+- The new address is free: the verb refuses one held by another account, in the
+  plan already.
+
+## Steps
+```bash
+# 1. Plan — runs every check, writes nothing
+plexus-cli --env <env> users set-email <old@domain> --to <new@domain>
+
+# 2. Apply
+plexus-cli --env <env> users set-email <old@domain> --to <new@domain> --confirm
+```
+
+For a test account, keep the local part and replace the domain's TLD with
+`.test` (RFC 2606/6761): `test100@<domain>.com` → `test100@<domain>.test`,
+`ada@<schule>.de` → `ada@<schule>.test`.
+
+## Verify
+```bash
+plexus-cli --env <env> users show <new@domain>     # same userId, same tenants
+plexus-cli --env <env> users show <old@domain>     # → No user with email …
+```
+
+## Idempotency / gotchas
+- Re-running with the address already moved prints "no change".
+- One identity, every tenant: an account shared by several tenants moves in all
+  of them at once. (Staff editing the party's E-Mail field cannot do this — that
+  path refuses a shared identity and points here.)
+- The password is untouched; set one afterwards with `users set-password` if needed.
+- **Mailbox proof** is reset (the holder re-confirms via a mailed link before
+  they can move a process again) — except for a reserved test address (`.test`,
+  `.example`, `.invalid`, `.localhost`, `example.com/.net/.org`): no mailbox
+  exists there, so the proof stays as it was (`proof: unchanged`), and no mode ever transmits
+  such an address (`skipped: reserved_address`).
+- **Config-declared accounts** (a staff roster in tenant config): re-export the
+  tenant config afterwards (`plexus-cli --env <env> --tenant <slug> config export`).
+  Applying an older export that still names the old address re-creates an
+  identity on it — config accounts are matched by e-mail.
+- Only the login changes. Old addresses in history (sent deliveries, value
+  history, contract snapshots) stay as they were; a queued delivery to the old
+  address ends `skipped: recipient_changed`.
+- An account-LESS party's e-mail (a contact, a second parent) is a stored value,
+  not a login — change it with `plexus-cli call parties:updateValue …` instead.
+
+## Related
+- [Set (rotate) a user's password](./set-password.md)
+- [Debug a mail delivery](../notifications/debug-mail-delivery.md)

package/dist/skill/references/users/cli-access-for-tenant-admin.md

@@ -0,0 +1,117 @@
+# CLI access for a tenant admin
+
+**When to use:** a school's own administrator (no platform rights) should run
+`plexus-cli` for **exactly their tenant**: export, plan and apply its config
+(`config export|apply|set`) and its admission offers (`offer …`). Example: the
+administrator of one school group onboarding their own offers.
+
+The person gets a `plx_…` token that acts **as them**. It reaches exactly the
+tenants their own login reaches — no other tenant, no platform surface. **A token
+works only while its owner holds `administration.apiTokens.manage`** (platform:
+`_platform.apiTokens.manage`): every CLI call asks the right again, and the
+change that takes the right away revokes the person's tokens.
+
+## Prerequisites
+- **The person is a tenant member with a login.** No login yet →
+  [Add a tenant admin](./add-tenant-admin.md) first.
+- **Every `tenant_admin` holds the three CLI rights** — `administration.apiTokens.manage`
+  (mint a token), `administration.config.read` / `.manage` (config, held
+  **tenant-wide**). They are part of the derived `tenant_admin` and reach existing
+  tenants on every deploy; nothing to grant. Someone outside `tenant_admin` needs a
+  group holding them.
+- **Offer commands** need `bewerbungsmanagement.forms.configure` (in `tenant_admin`).
+  A config change to groups or members also needs
+  `administration.permissions.manage` / `.users.manage` (in `tenant_admin`).
+- **Your auth (issuing for them):** a platform token with `_platform.users.manage`
+  **and** `_platform.apiTokens.manage` — the token acts as the person.
+- `--env` is required for the write; prod also needs `--allow-prod`.
+
+## Steps
+
+**0 — check the person is a `tenant_admin`:**
+
+```bash
+plexus-cli --env <env> users show <email>     # groups: tenant_admin, …
+```
+
+**A — the administrator mints it themselves:** in the app, *Einstellungen →
+API-Token* („Token erstellen"), or with a token they already have:
+`plexus-cli --env <env> tokens create laptop`.
+
+**B — the platform issues it for them** (to hand over directly):
+
+```bash
+plexus-cli --env <env> tokens create cli --for <email> --output /tmp/token-<slug>.csv --quiet
+```
+
+- The token is shown **once**. `--output` appends `email,token` to the CSV (a file
+  with a different header, e.g. a password file, is refused); `--quiet` keeps it out
+  of stdout. Without `--output`, it is printed.
+- Refused when the address has no account (`kein Konto`), no login, or holds
+  `administration.apiTokens.manage` in no tenant (`in keinem Mandanten`) — including
+  platform operators, who are tenant-less.
+- The token records who issued it.
+
+**The administrator's setup** (`~/.config/agent-tools/plexus.yml`; see SKILL.md →
+Connect, or `plexus-cli --help`). The platform operator provides the staging URLs:
+
+```yaml
+plexus:
+  default_env: staging
+  default_tenant: <slug>
+  environments:
+    staging: { convex_url: "https://<staging-convex-url>", site_url: "https://<staging-site-url>", token: "plx_…" }
+    # Required even without a prod token: every write compares its target with
+    # the prod URL (refused otherwise: "names no environments.prod.convex_url").
+    prod:    { convex_url: "https://db.plexus.swop.schule", site_url: "https://actions.db.plexus.swop.schule" }
+```
+
+## Verify
+
+As the administrator's token:
+
+```bash
+plexus-cli --env <env> whoami
+plexus-cli --env <env> config export --tenant <slug> --out ./<slug>/config.json   # passes
+plexus-cli --env <env> config export --tenant <other-slug> --out /tmp/x.json     # FORBIDDEN / NOT_FOUND
+plexus-cli --env <env> config apply --tenant <slug> --from snapshot:./<slug>/config.json  # dry run passes
+```
+
+## What a tenant-scoped apply refuses (FORBIDDEN, naming the field)
+- a tenant that does not exist (no onboarding), `--from blueprint`, `--allow-destructive`;
+- any `tenant.*` setting except `branding`, `brandingAssets`, `notificationChrome`
+  differing from live — modules (`enabledModules` decides the permission allowlist),
+  `defaultApplicantGroupKey`, `mailLevel`, `magicLinkLogin`, terms, …;
+- the import `source`;
+- a `foundation.users` address that is not an **active** member with a login (no new
+  accounts, no other tenant's people, no revoked member brought back);
+- a `_platform.*` right in any permission group.
+
+A change to the permission groups additionally needs `administration.permissions.manage`,
+a change to `foundation.users` (who sits in which group) `administration.users.manage` —
+the rights the app asks for the same act (`tenant_admin` holds both).
+
+Copy those values from `config export` unchanged; a change to them is a platform task.
+Platform-only regardless: `config wipe`, `config prune-offers`, `config apply --scope
+platform`, setup mode (Load N / wipe), `offer hard-delete`.
+
+## Idempotency / gotchas
+- Minting again makes a **second** token; revoke the old one with `tokens list` →
+  `tokens revoke <id>`. Without the right, the CLI refuses every call — listing and
+  revoking your own tokens then works in the app (Settings → API-Token) only.
+- Taking the right away (group removed or narrowed, tenant access ended, user
+  deactivated, module dropped by `config apply` or the deploy, platform right
+  dropped) **revokes** the person's tokens in the same change. Giving the
+  right back does not revive them — mint a new one. The exchange then answers 401
+  „Das API-Token „…“ wurde am <Datum> widerrufen: <Grund>“. A right that lapses without a
+  write is still caught: every CLI call asks it and refuses with 403 „Ihr Konto hat
+  das Recht „API-Tokens: Verwalten“ nicht mehr …“.
+- A tenant member cannot be made platform admin (`users set-platform-admin`):
+  platform rights and tenant access exclude each other — an inactive access row
+  counts too.
+- A unit-scoped membership does not count for config: the right must be held
+  tenant-wide.
+
+## Related
+- [Add a tenant admin](./add-tenant-admin.md) — the login itself.
+- [Edit a live tenant's offer](../offer/edit-live-tenant-offer.md).

package/dist/skill/references/users/delete-permission-group.md

@@ -0,0 +1,76 @@
+# Delete a tenant permission group
+
+Remove a permission group that should not exist — typically one created by an
+accidental click in Administration → Berechtigungen, which the admin UI can
+create and rename but **not** delete.
+
+## When to use
+
+- A stray group ("Neue Berechtigungsgruppe") with no members.
+- A team that was retired and whose work has been re-pointed elsewhere.
+
+Not for: taking someone's access away — that is `users unset-group` (leave the
+group, keep the tenant) or `users remove` (revoke tenant access).
+
+## Prerequisites
+
+- `bewerbungsmanagement`-independent: the mutation gates on the tenant's
+  **permissions-manage** grant, so a tenant admin or platform admin token.
+- The group must be genuinely unreferenced (see *Guards*).
+
+## Commands
+
+```bash
+# 1. See what the tenant has.
+plexus-cli --env prod users groups --tenant <slug>
+
+# 2. Dry-run — prints the member count it would be deleting against.
+plexus-cli --env prod users groups delete neue_berechtigungsgruppe \
+  --tenant <slug>
+
+# 3. Commit.
+plexus-cli --env prod users groups delete neue_berechtigungsgruppe \
+  --tenant <slug> --confirm --allow-prod
+```
+
+## Verify
+
+```bash
+plexus-cli --env prod users groups --tenant <slug>   # key is gone
+```
+
+Config is DB-authoritative, so the group is gone from the tenant's config too. A
+platform operator can confirm it in a `config export` (`foundation.permissionGroups`).
+
+## Guards (the delete REFUSES when…)
+
+| Refusal | Meaning | Fix first |
+|---|---|---|
+| `has-members` | Someone is still in the group (the message names them) | `users unset-group` each |
+| `owns-teams` | A running application binds this group as a work owner | Re-assign those applications |
+| `referenced-by-workflow` | A stored graph routes a decision/assign (or a not-yet-migrated legacy team-owner binding) to this key | Re-point the node, re-publish |
+| `structural` | It is `tenant_admin` | — (never deletable) |
+| `default-applicant` | It is the tenant's `defaultApplicantGroupKey` | Point the default at another group |
+| `unknown` | No group with that key in this tenant | Check `users groups` |
+
+## Gotchas
+
+- **Hard delete, on purpose.** There is no soft delete and no `--restore`. A
+  hidden-but-present group would need an `active` flag every reader honours, and
+  a reader that forgets one leaves a ghost — exactly the bug that let a removed
+  user keep a `user_tenant_access` row and made `config export` throw for that
+  tenant. Re-creating an empty group is one click; a ghost is a day of debugging.
+- **The group's `custom_field_permissions` go with it.** Those grants are the
+  group's own field visibility settings and mean nothing without it. Everything
+  else refuses rather than cascades.
+- **Key, not label.** `users groups delete` takes the stable `key`
+  (`neue_berechtigungsgruppe`), never the display label — renaming a group must
+  not change what the command targets.
+
+## Related
+
+- [Add a tenant admin](./add-tenant-admin.md)
+- [Update a tenant's config](../config/update-tenant-config.md) — the declarative
+  route: drop the group from the exported config and `config apply --confirm
+  --allow-destructive` sweeps it as an orphan. Equivalent outcome; use the CLI
+  verb for a one-off, the config route when the change belongs in the file.

package/dist/skill/references/users/grant-cross-tenant-access.md

@@ -0,0 +1,57 @@
+# Grant every tenant's users access to another tenant
+
+**When to use:** let **all existing users of every tenant** reach one shared tenant
+— the canonical case is giving every client access to the **Test Tenant** (`test`)
+so they can dogfood the product. One-time + manual: it grants the users that exist
+**now**; new users are **not** auto-enrolled (re-run later to pick up newcomers).
+
+> Pair this with the Test-Tenant feedback-privacy rule: the Test Tenant grants no
+> `administration.feedback.viewAll` (part of the `test` tenant's config), so
+> "Alle Rückmeldungen" is unavailable
+> there and each client only sees their own feedback.
+
+## Prerequisites
+- **Env:** target with `--env <local|staging|prod>` (this is a platform operation —
+  no `--tenant` needed). `plexus-cli --env <env> tenants` lists the reachable slugs.
+- **Auth:** a platform-admin token with `_platform.users.manage`. Confirm with
+  `plexus-cli --env <env> whoami`.
+- **Tooling:** an installed `plexus-cli` (`plexus-cli users grant-all --help`).
+
+## Steps
+Run once per **source** tenant, pointing every one at the target (`test`):
+```bash
+# Repeat for each non-test tenant slug:
+plexus-cli --env <env> users grant-all --from <sourceSlug> --to test --group tenant_admin
+```
+
+To enumerate the source slugs to loop over:
+```bash
+plexus-cli --env <env> tenants            # list slugs; run grant-all for each but `test`
+```
+
+- `--group tenant_admin` (the default) lets the granted users explore every module in
+  the Test Tenant. Pass a different group key for a narrower role.
+- Each user is granted idempotently; a user who already has access is a no-op.
+- Platform operators (tenant-less identities) never appear in a tenant's user set and
+  are additionally rejected by the `_platform.* XOR tenant-access` invariant — they
+  show up under `skipped` with a reason rather than aborting the run.
+
+## Verify
+```bash
+plexus-cli --env <env> users show <someEmailFromSource>
+```
+
+Success: the user now lists the `test` tenant with group `tenant_admin, applicant`.
+The command output also prints `Granted N/M users …` plus any `skipped` rows.
+
+## Idempotency / gotchas
+- **Current users only** — there is no standing auto-grant; re-run to enroll users
+  added after the last run.
+- Re-running is safe (idempotent per user); it neither rotates passwords nor creates
+  logins (contrast `users provision`).
+- Runtime-only grants — a destructive reseed of the source/target tenant drops them;
+  re-run this playbook afterwards.
+
+## Related
+- [Add a tenant admin](./add-tenant-admin.md) — single ready-to-log-in account.
+- Command reference: `plexus-cli users grant-all --help`.

package/dist/skill/references/users/grant-feedback-assignable.md

@@ -0,0 +1,43 @@
+# Make a platform admin assignable to feedback issues
+
+**When to use:** a platform admin should appear in the feedback-board assignee
+picker (and be a valid `feedback assign` target). Being a platform admin is **not**
+enough — assignability is the opt-in `_platform.feedback.assign` permission, granted
+explicitly to the platform's real triage admins only.
+
+## Prerequisites
+- `--env staging|prod` configured with a platform-operator token (the grant is gated
+  `_platform.users.manage`).
+- The target already exists as a platform admin (`plexus-cli --env <env> platform users`).
+
+## Steps
+```bash
+plexus-cli --env <env> users set-platform-permission <email> \
+  --permission _platform.feedback.assign --on
+```
+Example — grant one triage admin on prod:
+```bash
+plexus-cli --env prod users set-platform-permission --allow-prod ada@example.com \
+  --permission _platform.feedback.assign --on
+```
+
+## Verify
+```bash
+# The assignee picker lists EXACTLY the assignable admins:
+plexus-cli --env <env> feedback admins
+```
+
+## Idempotency / gotchas
+- **Opt-in, not part of the full-admin grant.** Making someone a full platform admin
+  (`users set-platform-admin … --on`) does **not** grant assignability; this perm is
+  excluded from the default set on purpose. Re-affirming full-admin status *preserves*
+  an already-granted assign perm (it is never silently stripped).
+- Revoke with `--off`. Removing the last permission from a row deletes the
+  `platform_admins` row entirely (the identity stays a normal user).
+- `_platform.* XOR tenant-access`: the grant fails loud if the identity has tenant
+  access (platform operators must be tenant-less).
+- Re-running `--on` is a no-op (the perm is added once).
+
+## Related
+- [Add a platform admin](./add-platform-admin.md) · [Add a platform user](./add-platform-user.md)
+- [Create + triage feedback from the CLI](../feedback/create-and-triage-feedback.md)

package/dist/skill/references/users/set-password.md

@@ -0,0 +1,57 @@
+# Set (rotate) a user's password
+
+**When to use:** an existing user — tenant user **or** platform admin — needs a new
+login password (reset a lost one, or set a known value). This only changes the
+password; it grants nothing and creates nothing.
+
+## Prerequisites
+- **Env:** target with `--env <local|staging|prod>`. No `--tenant` — the command
+  finds the identity by email globally.
+- **Auth:** a token with `_platform.users.manage` (your platform-admin token, no
+  Convex admin key). Confirm with `plexus-cli --env <env> whoami`.
+- **Inputs:** the user's email. The identity **must already exist** (provision it
+  first with [add-tenant-admin](./add-tenant-admin.md) /
+  [add-platform-admin](./add-platform-admin.md)).
+- **Tooling:** an installed `plexus-cli` (`plexus-cli users set-password --help`).
+
+## Steps
+```bash
+# Set a known password:
+plexus-cli --env <env> users set-password <email> --password 'NewPassw0rd!'
+
+# …or let the server generate a strong one (returned once; capture without echoing):
+plexus-cli --env <env> users set-password <email> --output creds.csv --quiet
+```
+
+The server owns hashing + generation and returns the plaintext **once** (only the
+hash is stored). `--output creds.csv` appends the `email,password` row; `--quiet`
+keeps it off stdout.
+
+## Verify
+```bash
+plexus-cli --env <env> users show <email>     # identity unchanged (sanity)
+```
+Then confirm the new password actually logs in at the env's `/login`.
+
+## 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
+- **Pure credential write** — it creates no identity, tenant access, person, or
+  permission, and changes no groups. Use `users provision` /
+  `users provision-platform-admin` to *create* a ready-to-log-in user;
+  `set-password` only rotates an **existing** one.
+- **Fails loud, never repairs by creating:** throws if no Plexus identity exists for
+  the email, if the email has no live Better Auth account, or if that account
+  doesn't match the identity (an orphan → run `users relink-auth` first, then retry).
+- The password is shown **once**; re-run to mint a fresh one if you lose it.
+- Email match is case-insensitive (the backend lowercases it).
+
+## Related
+- [Add a tenant admin](./add-tenant-admin.md) · [Add a platform admin](./add-platform-admin.md)
+  — both also accept `--password` at creation time.
+- `users relink-auth <email>` — repair an orphaned identity before setting a password.
+- Command reference: `plexus-cli users set-password --help`.