@smartkomm/plexus-cli 0.0.0-stage → 0.1.1

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

package/dist/skill/references/users/use-test-account.md

@@ -0,0 +1,79 @@
+# Use a tenant's test account
+
+**When to use:** you want to walk a school's actual admission process as an
+applicant — on local, staging or prod — without registering a new address first.
+
+## Prerequisites
+
+- The account exists already in every tenant with an applicant portal:
+  `config:bootstrap` provisions it on every deploy, `config apply` on every
+  tenant onboarding, and the local development seed. Nothing to create.
+- Identity: **`test@example.com`** ("Test Bewerber", stable key `fixture_test`
+  on `user_tenant_access.configKey`), a member of the tenant's applicant group.
+- Staging/prod: a platform admin (`_platform.users.manage`) to set its password
+  once per deployment.
+
+## Steps
+
+### 1. Check the account in the target tenant
+
+```bash
+plexus-cli --env <local|staging|prod> users show test@example.com
+```
+
+Expect one access row per tenant with an applicant portal, each in the
+`applicant` group.
+
+### 2. Set a password (staging / prod, once per deployment)
+
+A deploy provisions the account with a random password nobody holds. Set one:
+
+```bash
+plexus-cli --env <staging|prod> --tenant <slug> users set-password test@example.com
+```
+
+The identity is global, so this one password opens the account in **every**
+tenant of that deployment. The plaintext is printed once — password manager,
+not a ticket.
+
+**Local** needs no password: the account carries the dev-login marker, so
+`/login?as=test@example.com&redirect=/<slug>/e` signs in as it.
+
+### 3. Apply
+
+Open `https://<host>/<slug>/e`, start the offer, fill the form — the same
+surfaces a parent uses.
+
+## Verify
+
+```bash
+# It is the test row of "Wer ist der Antragsteller?" (needs testActions.run).
+plexus-cli --env <env> call admission:testApplicantParties client=<slug>
+```
+
+## Gotchas
+
+- **Every application of it is a test application.** Started by the
+  account itself through the portal (any Testmodus checkbox is irrelevant) or
+  by staff from the internal „+ Bewerbung" dialog (its amber first row, for
+  anyone with `bewerbungsmanagement.testActions.run`; refused without it), the
+  server derives test mode from the key. Discard it like any test application.
+- **Mail.** Never sent, in any mode (staging `redirect` included):
+  `example.com` is a reserved test address, so the delivery is rendered and
+  recorded and settles `skipped` / `reserved_address` — sign in with the
+  password, not a magic link.
+- **A deploy never rotates the password.** An existing credential is preserved,
+  so a password you distributed survives every `config:bootstrap`.
+- **Identity is the key, not the name.** Renaming "Test Bewerber" moves the row;
+  it never creates a second account.
+- **A real account on `test@example.com` fails the deploy** (`config:bootstrap`
+  throws "not the test fixture"). Move that account to another address first.
+- **Not in `config export`.** The account is platform-provisioned, so it is
+  never emitted as a config user.
+- Skipped (and named in the bootstrap result under `fixtures.skipped`): tenants
+  without a `defaultApplicantGroupKey`, and the reserved `_platform` tenant.
+
+## Related
+
+- [Drive a test application through test mode](../test-actions/drive-a-test-application.md)
+- [Set (rotate) a user's password](./set-password.md)

package/dist/skill/references/worker-ops/debug-worker-jobs.md

@@ -0,0 +1,90 @@
+# Debug a stuck / failed import or worker job
+
+**When to use:** an import shows "running" but looks stuck, the Worker console
+shows no active worker, a job failed and you need to know why, or you must clean
+up a stranded import run. This is the **canonical agent debugging setup** for the
+worker/job system: `plexus-cli` for the LIVE job/worker/import state +
+`glitchtip-cli` for the captured stack traces.
+
+## Prerequisites
+- `--env local|staging|prod`; the new worker/job commands need **platform-admin**
+  (the configured token already is, on staging/prod).
+- For the stack traces: access to the platform's GlitchTip (the error tracker the
+  worker reports to), e.g. through `glitchtip-cli` (`glitchtip-cli info` shows the
+  server + auth). That is platform-operator access; without it, ask the operator.
+
+## Steps
+
+```bash
+# 1. Live fleet: is any worker alive, and what is it running right now?
+plexus-cli --env prod platform workers --json        # lifecycle live|stale|dead, currentJob
+
+# 2. The jobs themselves (generic queue). Filter to what's stuck/broken.
+plexus-cli --env prod jobs list --status running     # genuinely in flight
+plexus-cli --env prod jobs list --status failed --kind import
+plexus-cli --env prod jobs show <jobId>              # lease, attempts, phase, error, run timeline
+plexus-cli --env prod jobs logs <jobId>             # captured worker stdout/stderr
+
+# 3. Import-domain view (imports stuck "still running" live here, NOT in jobs).
+plexus-cli --env prod imports status --tenant <slug>
+
+# 4. Captured exceptions for the failure (stack trace + tags).
+glitchtip-cli issues list
+#   GlitchTip event tags the worker attaches: errorSource=backend:worker,
+#   jobKind, jobId, importRunId, configKey. Filter by them via GlitchTip's API
+#   (the CLI `issues list` has no tag filter).
+
+# 5. Is the reaper (the only authority that frees stuck leases) actually firing?
+plexus-cli --env prod workers reaper-status --json   # ranAt should be < ~1 min old
+```
+
+### The decision rule (why did the worker die?)
+
+A job reaper-failed / vanished, **and**:
+- **GlitchTip HAS an event** → it was a JS throw. Read the stack in the issue.
+- **GlitchTip has NO event** → uncatchable **OOM/SIGKILL**. The only trace is the
+  reaper-failed job; its error message names the last phase + idle time (e.g.
+  *"vanished during phase 'importing' after N min"*). Confirming it needs a
+  platform operator with host access: the worker container's **exit code 137**
+  (or the kernel's OOM-killer log).
+
+## Recovery
+
+```bash
+# Force a reaper pass now instead of waiting for the 1-min cron.
+plexus-cli --env prod workers reap --allow-prod --json
+
+# Clear import runs stuck 'running' with no active job (the orphan class).
+# DRY-RUN first (no --confirm), then confirm. Marks failed, never deletes.
+plexus-cli --env prod imports cleanup-orphaned --tenant <slug>
+plexus-cli --env prod imports cleanup-orphaned --allow-prod --tenant <slug> --confirm
+plexus-cli --env prod imports cleanup-orphaned --all-tenants            # dry-run sweep
+
+# Cancel a job that should not be running.
+plexus-cli --env prod jobs cancel --allow-prod <jobId>
+```
+
+## Verify
+
+```bash
+plexus-cli --env prod imports status --tenant <slug>   # the stuck run now 'failed'
+plexus-cli --env prod jobs list --status running       # nothing unexpectedly in flight
+```
+
+## Idempotency / gotchas
+- `cleanup-orphaned` and `jobs cancel` flip rows to **failed/canceled**, never
+  delete — history is preserved. `cleanup-orphaned` is dry-run unless `--confirm`.
+- Since the terminal-state fix (the job registry's `onTerminal` hook), a job
+  that terminally fails now propagates to its `import_runs` row automatically —
+  **new** orphans shouldn't appear; `cleanup-orphaned` is for pre-fix strays and
+  as a backstop.
+- The **reaper** only touches the generic `jobs` table (frees leases / fails
+  stalled jobs); it does **not** scan `import_runs`. A "running" import with all
+  workers idle = an orphaned domain row → use `cleanup-orphaned`.
+- `jobs list --kind` filters client-side after paging; raise `--limit` if you page
+  past the row you want.
+
+## Related
+- [Verify that a deploy's migrations ran](./verify-migrations.md)
+- Command reference: `plexus-cli jobs list --help`, `plexus-cli workers reap --help`,
+  `plexus-cli imports cleanup-orphaned --help`.

package/dist/skill/references/worker-ops/verify-migrations.md

@@ -0,0 +1,51 @@
+# Verify that a deploy's migrations ran
+
+**When to use:** after a staging or production deploy whose release lists
+pending migrations (the release's `PENDING_MIGRATIONS` list), when you need the
+state from the deployment itself rather than from the deploy log. The deploy job
+already prints, by name, the dry run of the next migration, every migration that
+ran (with its document count) and a final check that every pending entry is
+`success` — it goes red if any is not; that log is the platform operator's.
+
+## Prerequisites
+- `--env staging|prod` (or `local` for a local development backend).
+- The CLI token's user holds `_platform.config.read` (every full platform
+  admin does). Anyone else gets `FORBIDDEN`.
+
+## Steps
+
+```bash
+plexus-cli --env staging migrations status            # pending migrations, exit 1 while one is not success
+plexus-cli --env staging migrations status --recent   # + the 20 most recently started of any name
+plexus-cli --env staging migrations status --json     # raw answer + `unfinished`
+```
+
+A release script gates on the exit code instead of grepping the output:
+`plexus-cli --env prod migrations status || exit 1`.
+
+Underneath it reads `migrations:getStatus`, which returns two lists of `{ name, state, isDone, processed, error, latestStart, latestEnd }`:
+- **`pending`**: every entry of `PENDING_MIGRATIONS`, in run order. After a good
+  deploy each one reads `state: "success"`, `isDone: true`. A name that reads
+  `unknown` never started on this deployment.
+- **`recent`**: the 20 most recently started migrations of any name, newest
+  first. Use it to see what the last deploy actually touched.
+
+## Verify
+- Every `pending` entry is `success`, and `latestEnd` is after the deploy's
+  workflow run started.
+- `pending` is empty when the release carries no migration. Then there is
+  nothing to verify, and the migration step only pushed functions.
+
+## Gotchas
+- `failed` or `canceled` with an `error`: `runPending` threw and the deploy
+  stopped before the config bootstrap. Read the error here; the host-side output
+  is in the deploy log (platform operator).
+- `inProgress` long after the deploy means the migration is stuck. Hand it to a
+  platform operator; do not try to restart it from the CLI.
+- A local development backend lists every pending migration as `unknown` (exit 1): the seed
+  builds data in the new shape and never runs migrations. Only staging/prod answer the question.
+- „Could not find public function migrations:getStatus“: the CLI points at a deployment
+  without this release (often a local development backend that never received the
+  functions). Check `--env` (`plexus-cli config show`).
+- The query shows names, state, progress and errors only; it never returns a
+  cursor or document data.