@smartkomm/plexus-cli 0.0.0-stage → 0.1.1

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

package/dist/skill/references/config/init-tenant.md

@@ -0,0 +1,121 @@
+# Scaffold a brand-new tenant config from nothing
+
+**When to use:** stand up a brand-new customer (tenant) from *nothing* — no snapshot,
+no `.dev` export, no other environment to promote from. `config init` writes the
+smallest valid config to disk; you then `config apply` it. If a config source already
+exists (a `.dev` export / a tenant in another env), use
+[Onboard / establish a tenant](./onboard-tenant.md) instead — that path skips the
+scaffold.
+
+## Prerequisites
+- **Env:** target with `--env <local|staging|prod>`. Tenant creation is implicit in
+  `config apply` (there is no separate "create tenant" verb). `config init` itself is
+  **offline** — no deployment, no auth.
+- **Auth (for the apply, not the init):** a platform-admin token (`config apply` is
+  gated on `_platform.config.manage`). Confirm with `plexus-cli --env <env> whoami`.
+  The local admin-key fallback has no platform identity and is rejected — drive
+  `--env local` with a token too. A tenant admin's token cannot do this: a
+  tenant-scoped apply refuses a tenant that does not exist yet
+  ([CLI access for a tenant admin](../users/cli-access-for-tenant-admin.md)).
+- **Tooling:** an installed, current `plexus-cli` (`plexus-cli --help`).
+- **Prod:** every writing run against prod needs `--allow-prod` (`config apply`,
+  `users provision`); without it the CLI refuses.
+
+## Decide before you apply
+
+Settle these with the school first — each one is a later playbook, but the answers
+belong to onboarding:
+
+| Decision | Default of the scaffold | Where it is set |
+|---|---|---|
+| Slug + display name | — (`--tenant`, `--name`) | step 1; the slug is the identity, never rename it |
+| Modules the school bought | **all** grantable module permissions | trim `tenant.permissions` in the scaffold before step 4 |
+| „Bewerbung" or „Anmeldung" | Bewerbung (no `terms` in the scaffold) | [Set a school's terms](./set-tenant-terms.md) |
+| Which mail families get | `all` („Alle E-Mails“) | [Mail level](../notifications/mail-level.md) |
+| Portal branding (colors, logo, fonts) | neutral | [Set tenant branding](./set-tenant-branding.md) |
+| Payments / e-signature | none | [Stripe](../stripe/connect-a-school.md) · [Signing](../signing/connect-a-school.md) |
+
+**Look at an existing tenant as a reference.** Export one you can reach into a private
+scratch dir and compare:
+`plexus-cli --env prod config export --tenant <existing slug> --out <scratch>/ref.json`.
+
+## Steps
+```bash
+# 1. Scaffold a minimal, valid tenant config (offline — no deployment, no auth).
+plexus-cli config init --tenant <slug> --name "<Display Name>" \
+  --out config/.dev/<slug>/config.json          # --out defaults to this path
+
+# 2. (Optional) edit config/.dev/<slug>/config.json — add custom fields, roles,
+#    extra units/legal entities, a `source` block if this tenant imports data, etc.
+#    The scaffold has NO `source` block: a tenant that never imports needs none.
+
+# 3. Dry-run the apply (shows the create/update plan; writes nothing).
+plexus-cli --env <env> config apply --tenant <slug> \
+  --from snapshot:config/.dev/<slug>/config.json
+
+# 4. Commit it.
+plexus-cli --env <env> config apply --tenant <slug> \
+  --from snapshot:config/.dev/<slug>/config.json --confirm
+
+# 5. Provision the generic admin login (separate auth plane — see related playbook).
+#    Convention: admin@<short>.plexus.swop.schule, name "<Short> Administration",
+#    so a platform operator always has one login per school that belongs to no person.
+plexus-cli --env <env> --tenant <slug> users provision admin@<short>.plexus.swop.schule \
+  --name "<Short> Administration" --group tenant_admin --output creds.csv --quiet
+```
+
+Write `config/.dev/…` and `creds.csv` to a private scratch dir — never put a real
+tenant's config or a password into a shared or public place. Hand the credentials over
+in the three-line format of
+[Add a tenant admin](../users/add-tenant-admin.md#hand-the-credentials-over--always-this-format).
+Staff of the school get their own accounts the same way (their address, their name);
+the generic admin is not shared with them.
+
+**Created for you, not by you:** the apply also provisions the tenant's test applicant
+`test@example.com` („Test Bewerber"), which then shows up in `users list` with the new
+slug. That is intended — see [Use a tenant's test account](../users/use-test-account.md).
+
+The scaffold emits the smallest config `apply` accepts: the tenant block (all
+grantable module permissions + `defaultApplicantGroupKey`), one school operator
+(legal entity), **one pedagogy unit** (the school offers link to), the `tenant_admin`
++ `applicant` permission groups, and one display group (required — the system
+identity fields attach to it). No users (provision them in step 5) and no `source`.
+It is built by the same code that builds the platform's demo tenant, so the
+scaffolded permission sets can never drift from it.
+
+## Verify
+```bash
+# The tenant + its foundation now exist:
+plexus-cli --env <env> --tenant <slug> config targets   # foundation rows > 0
+plexus-cli --env <env> --tenant <slug> config export     # round-trips the unit, groups
+plexus-cli --env <env> tenants                            # <slug> is listed
+```
+
+Then, in this order: the decisions above (terms, mail level, branding, payments) →
+offers on the pedagogy unit: `offer init --unit <unit key> --title … --title-en … --responsible <staff configKey>` →
+`offer apply --publish` (see `plexus-cli offer --help` and
+[Publish an offer bundle](../offer/publish-offer-bundle.md)).
+
+## Idempotency / gotchas
+- **`config init` is offline and overwrites `--out`** — re-running regenerates the
+  same skeleton from `--tenant`/`--name`; it does not touch any deployment.
+- **`config apply` is idempotent** — re-running reconciles to the config (no
+  duplicate tenant). Dry-run first; only `--confirm` writes.
+- **`source` is optional.** Omit it for a non-importing tenant; add it only when
+  wiring a master-data import. Import code fails loud at import time if a source is
+  needed but absent — there is no fake-source fallback.
+- **Teardown:** only `config wipe --target all --confirm --allow-destructive` deletes
+  the tenant **identity row** — after purging its applications and draining every
+  target, files included (only the logo stays: sent mail links it). `--target foundation` (even with `--cascade`) clears
+  child tables + dependent data but leaves the tenant row and sibling config targets —
+  by design (`tenants` is excluded from every wipe target). The CLI prints a note when
+  you wipe a non-`all` target so this is never a surprise.
+- Staff accounts are a **separate plane** (Better Auth) — the config never creates
+  logins; provision them with `users provision` (step 5).
+
+## Related
+- [Onboard / establish a tenant](./onboard-tenant.md) — establish from an existing
+  `.dev` export / env (the non-scaffold path).
+- [Update a tenant's config](./update-tenant-config.md) · [Wipe a tenant's config](./wipe-tenant-config.md)
+- [Add a tenant admin](../users/add-tenant-admin.md) — the credentialed login (step 5).
+- Command reference: `plexus-cli config <verb> --help`.

package/dist/skill/references/config/onboard-tenant.md

@@ -0,0 +1,71 @@
+# Onboard / establish a tenant
+
+**When to use:** stand up a real tenant's config-as-code in an environment for the first time
+(or refresh it). A real tenant's config lives in the database (DB-authoritative) and is
+established from a snapshot or another environment — never from built-in seed data.
+
+## Prerequisites
+
+- `plexus-cli` installed; platform-admin token for the target env (`_platform.config.manage`).
+- A config **source** for the tenant, one of:
+  - a `config export` from another env (default path `config/.dev/<slug>/config.json`),
+  - an environment that already has the tenant (promote with `--from env:<srcEnv>`).
+  A real tenant's config is kept nowhere but its deployment — prod is its source of truth, so a
+  refresh of staging comes FROM prod, never the other way round.
+- The `--tenant` value must be the **slug embedded in the snapshot** — apply rejects a mismatch.
+
+## Steps
+
+```bash
+# Establish from a snapshot (dry-run first, then commit).
+plexus-cli config apply --env <env> --tenant <slug> \
+  --from snapshot:config/.dev/<slug>/config.json
+plexus-cli config apply --env <env> --tenant <slug> \
+  --from snapshot:config/.dev/<slug>/config.json --confirm
+
+# OR copy a tenant that already exists on prod to staging (re-plans against the target's live state).
+plexus-cli config apply --env staging --tenant <slug> --from env:prod --confirm
+```
+
+**If the source carries `foundation.users`, the committing apply hands you passwords.**
+Every declared user without a login account gets one minted right here, printed once
+(`+ account <email> password: …`) — the server keeps only the hash. Redirect them instead
+of running this in a shared terminal:
+
+```bash
+plexus-cli config apply --env <env> --tenant <slug> \
+  --from snapshot:<path> --confirm --output creds.csv --quiet
+```
+
+The dry-run above mints nothing (`--output` is inert and creates no file); it lists the
+same users as `! no account <email>`, so you know beforehand whether the commit will emit
+secrets.
+
+After the config exists, iterate it live with [Update a tenant's config](./update-tenant-config.md),
+run the real import, and publish offers via `plexus-cli offer apply`.
+
+## Verify
+
+```bash
+plexus-cli config targets --env <env> --tenant <slug>   # registry + live per-tenant row counts
+plexus-cli config export  --env <env> --tenant <slug>   # full reconstructed config
+```
+
+## Idempotency / gotchas
+
+- `apply` is **idempotent and additive on config tables** — it never wipes the data plane
+  (parties/values/applications). Re-running an establish is safe.
+- **Deploys do not establish real tenants.** A staging/prod deploy applies only the
+  **template tenant** (`test`) — establishing a real tenant is this manual step.
+- The **import mapping is DB-authoritative**: `custom_fields.sourceColumns` ships in the config
+  and is read by the import worker. The import **fails loud** if a tenant has fields but none
+  carry `sourceColumns` — i.e. the worker was deployed before the tenant was (re)applied:
+  re-run this apply.
+- A structural schema change is a **migration** that a platform operator runs before the
+  apply — not part of onboarding, and not something the CLI does.
+
+## Related
+
+- [Update a tenant's config](./update-tenant-config.md) · [Wipe a tenant's config](./wipe-tenant-config.md)
+- [Scaffold a brand-new tenant config](./init-tenant.md) — when no source exists yet.
+- Command semantics: `plexus-cli config apply --help`.

package/dist/skill/references/config/rename-program-stage.md

@@ -0,0 +1,99 @@
+# Rename, add, reorder or retire a program stage (Klassenstufe)
+
+**Use it to** change an offer's Klassenstufen — rename "Kindergarten Jahr 1" to
+"Nursery 1", add a level, change the order, or retire one — without leaving a
+second, stale level behind and without cutting applications loose.
+
+## The model in one paragraph
+
+A stage is identified by the **key** in `bundle.yaml → program.stages[].key`, never
+by its name. The stored key is `<program.key>-stufe-<key>`. Applications, capacity
+cells and waitlists point at the stage row by id, so a rename that keeps the key
+keeps all of them. `offer apply` reconciles by key: same key → update, new key →
+insert, removed key → archive (refused while an active application sits on it),
+re-listed archived key → restore. Array order = display order.
+
+## Declaratively (bundle — preferred for anything you want reproducible)
+
+```bash
+# 1. Start from what is live — prod is the source of truth for a real tenant, so
+#    work on a fresh export in a scratch directory (export writes the bare keys back)
+WORK=$(mktemp -d)
+plexus-cli --env prod --tenant <slug> offer export --slug <offer-slug> --out $WORK/<offer-slug>
+```
+
+```yaml
+# 2. Edit program.stages — KEEP the key of every level you rename. A name is
+#    German AND English; changing only the English is a rename too.
+program:
+  stages:
+    - key: kindergarten-jahr-1     # existing level, new name
+      name: { de: Nursery 1, en: Nursery 1 }
+    - key: kindergarten-jahr-2
+      name: { de: Nursery 2, en: Nursery 2 }
+    - key: early-years-1           # new level
+      name: { de: Early Years 1, en: Early Years 1 }
+```
+
+```bash
+# 3. Offline check, then look at the stage rows of the plan
+plexus-cli offer validate --dir $WORK/<offer-slug>
+plexus-cli --env prod offer plan --dir $WORK/<offer-slug>
+#   ~  stage:kindergarten-jahr-1  ~stage kindergarten-jahr-1 ("Kindergarten Jahr 1" → "Nursery 1", en "Kindergarten year 1" → "Nursery 1")
+#   +  stage:early-years-1        +stage early-years-1 (Early Years 1)
+
+# 4. Apply
+plexus-cli --env prod offer apply --allow-prod --dir $WORK/<offer-slug>
+```
+
+## Imperatively (one-off, no bundle)
+
+```bash
+# --level takes the level's KEY; a German rename always needs --name-en (the
+# English is never copied from the German, and a name without English is refused).
+# Against prod: --env prod … --allow-prod
+plexus-cli --env <env> offer level rename  --slug <offer-slug> --level kindergarten-jahr-1 --name "Nursery 1" --name-en "Nursery 1"
+plexus-cli --env <env> offer level add     --slug <offer-slug> --name "Early Years 1" --name-en "Early Years 1" --key early-years-1
+plexus-cli --env <env> offer level remove  --slug <offer-slug> --level early-years-1
+plexus-cli --env <env> offer level restore --slug <offer-slug> --level early-years-1
+```
+
+After imperative changes, **export the bundle again before the next `apply`**:
+otherwise the old bundle still lists the old state, and applying it undoes your
+changes (renames them back, archives the added levels).
+
+## Verify
+
+```bash
+plexus-cli --env prod offer plan --dir $WORK/<offer-slug>   # no stage rows = in sync
+plexus-cli --env prod offer show --slug <offer-slug>                     # levels in order
+```
+
+## Gotchas
+
+- **Changing a key is not a rename.** A new key inserts a new level and archives the old
+  one. If the old one has active applications, the apply is refused — which is what you
+  want: those applications would stay on a level nobody sees.
+- **`[stage/hasActiveApplications]`** — the level you dropped (or `level remove`d) still
+  has active applications. `offer plan` shows it in advance: `-stage … — REFUSED: n
+  active application(s)`. Rename it instead, or close those applications first. No
+  stage was changed: the reconcile is one transaction. (The manifest draft and the
+  unit/program link apply wrote before it stay — unpublished; don't publish by hand.)
+- **A level moves to another offer** (e.g. Grade 12 moves from Primary to Secondary). Keys are per
+  program, so the target offer gets a *new* row and the source offer's row is archived.
+  Nothing re-points an application across programs. While applications are active on
+  the source row, keep the level listed in the source bundle and close its cell
+  (`offer capacity set --slug … --run … --level … --close`), then drop it in a later apply.
+- **`[stage/hasOpenLeads]`** is a warning, not a refusal: open Interessenten keep
+  pointing at the archived level and cannot be converted until they are moved to an
+  active level.
+- **`[stage/duplicateKey]` from apply but not from validate** — the stored key is taken
+  by a stage of *another* program in the tenant (keys are unique per tenant). Choose a
+  different key.
+- **A `-stage` row showing a key like `kindergarten:vorschule:lz3k9`** — a legacy stage
+  created in the master-data admin before stage keys existed, keyed outside the `<program>-stufe-`
+  scheme. No bundle key can address it, so `apply` archives it (through the guard).
+  `offer export` refuses such a row with `[stage/foreignKey]`. No CLI verb re-keys a
+  stage today — raise it with the platform operator instead of hand-editing around it.
+- A bundle **without** `program.stages` leaves the levels alone; `stages: []` archives
+  all of them (guarded).

package/dist/skill/references/config/set-tenant-branding.md

@@ -0,0 +1,150 @@
+# Set a tenant's external-portal branding
+
+**When to use:** give a tenant's public `/e/**` Bewerbungsportal its own white-label
+look — brand colors, corner radius, logo size, header style, and font families, plus an
+uploaded logo and uploaded font files — on staging and/or prod, without a reseed.
+
+## Prerequisites
+
+- `plexus-cli` installed and current (`plexus-cli --help`).
+- A token configured for each target env (`plexus-cli --env <env> config show` prints
+  the resolved connection): a platform-admin token holding `_platform.config.manage` (the
+  same right that gates `config apply`), or — for your OWN tenant only — a tenant
+  admin's token holding `administration.config.manage` (see
+  [CLI access for a tenant admin](../users/cli-access-for-tenant-admin.md)). Such a
+  token changes branding **only through `config apply`** (branding is one of the few
+  `tenant.*` settings it may change); every `plexus-cli branding …` command needs the
+  platform right and refuses it. A local admin key without a user identity does **not**
+  satisfy this gate.
+- The `plexus-cli branding …` commands must be **live on the target env** first (they
+  call backend functions of the same release). A platform operator rolls a release out
+  to staging, then prod; only then run the CLI.
+- The tenant **slug** (e.g. `test`). Always **stage on staging first**, verify in the
+  browser, then promote to prod.
+
+## The two halves of branding
+
+| Part | Where it lives | How to set it |
+| --- | --- | --- |
+| **Theme tokens** — colors, radius, logoSize, bannerDensity, filledHeader, websiteUrl, font **families** | `tenant_branding` row columns; config-portable (exported in `tenant.branding`) | `plexus-cli branding set-theme` (surgical) **or** `config apply` (whole-config) |
+| **Logo** | `_storage` id column (a single `primary` slot); carried by config **by hash** (`tenant.brandingAssets.logo`) | `plexus-cli branding set-logo` (one-off upload) **or** `config apply` (bytes from the snapshot / source env) |
+| **Font files** (WOFF2, one per slot `heading` / `body`) | `_storage` id columns; carried by config **by hash** (`tenant.brandingAssets.fontHeading` / `fontBody`) | `plexus-cli branding set-font --slot heading\|body --file <woff2>` **or** `config apply` |
+
+A `storageId` is deployment-local, so config never carries it. It carries each uploaded
+file like a library file: `{ sha256, sizeBytes, mimeType }` under `tenant.brandingAssets`, and
+`config export` downloads the bytes beside `config.json` as `branding/<slot>.<ext>`
+(`path` in the entry). `config apply --from snapshot:…` or `--from env:<src>` uploads
+only the files whose hash the target does not hold; the dry run prints
+`~ brand  branding/logo  content differs — would upload`. A missing slot — or a snapshot
+without the block — leaves the target's file untouched. A replaced **logo** file is never
+deleted (sent mail links it); a replaced **font** file is.
+Fonts are served from the app's own Convex origin — **never** point a browser at an
+external font host (a private-network host is blocked by the browser; the Google-Fonts
+CDN is a GDPR problem).
+
+## The theme shape
+
+Every field is optional — omit a key to fall back to the platform default:
+
+```jsonc
+{
+  "colors": {
+    "primary":    "#1E4BCD",   // brand primary → --color-primary (buttons, rings, filled header)
+    "accent":     "#0AAA5F",   // secondary accent → --color-accent (links, hovers, dots)
+    "background": "#FFFFFF",    // portal page bg → --color-bg
+    "foreground": "#111111"     // body text → --color-fg
+  },
+  "radius": "sharp",            // "sharp" | "rounded" | "soft"
+  "logoSize": "max",            // banner logo height: "sm" | "md" | "lg" | "max" (default lg)
+  "bannerDensity": "normal",    // "compact" | "normal" | "spacious" (default normal)
+  "filledHeader": false,        // true → top nav bar filled with the PRIMARY colour (on-primary text)
+  "websiteUrl": "https://www.example-schule.de",
+  "fonts": {
+    "heading": { "family": "Space Grotesk" },   // family only — the file is uploaded (set-font)
+    "body":    { "family": "Lora" }
+  }
+}
+```
+
+- `colors.*` are `#RRGGBB` hex strings; `radius`/`logoSize`/`bannerDensity` are the enums above.
+- A font entry is `{ family }`. With an uploaded file for that slot the portal loads it as
+  `@font-face` under that family; without one the family must already be available
+  (system/bundled). A font `url` is **refused** (`fonts.<slot>.url is no longer
+  supported`) — upload the file instead.
+- Bad values (malformed hex, bad enum, a font `url`) fail loud server-side — the write
+  aborts, no partial state.
+
+## Steps — the surgical CLI path (recommended)
+
+```bash
+# 1. Inspect current branding (branding + resolved logo URL).
+plexus-cli --env staging --tenant <slug> branding show
+
+# 2. Set the theme tokens from a JSON file (replaces the theme wholesale; leaves the logo).
+plexus-cli --env staging --tenant <slug> branding set-theme --file theme.json
+
+# 3. Upload the logo — from a local file …
+plexus-cli --env staging --tenant <slug> branding set-logo --file logo.png
+#    … or straight from a URL (fetched + uploaded by the CLI):
+plexus-cli --env staging --tenant <slug> branding set-logo \
+  --url https://cdn.example.com/logo-black.png
+
+# 4. Upload the font files — the slot's family must be set first (step 2), the file is
+#    applied under it. WOFF2 only (signature-checked), ≤ 2 MB; a replaced file is deleted.
+plexus-cli --env staging --tenant <slug> branding set-font --slot heading --file heading.woff2
+plexus-cli --env staging --tenant <slug> branding set-font --slot body    --file body.woff2
+#    (`branding clear-font --slot <slot>` removes a file; the family stays.)
+
+# 5. Verify, then promote to prod (re-run 1–4 with --env prod — never assume prod == staging).
+plexus-cli --env prod --tenant <slug> branding show
+```
+
+- `set-theme` replaces the whole theme (a submitted-absent field clears the stored one),
+  mirroring the admin form — so the file must carry the **complete**
+  theme you want.
+- The logo cap: images only, ≤ 3 MB. Pick the variant that reads on the header — a **dark
+  logo** for the default light bar, a **white/inverse logo** when `filledHeader: true`
+  (the bar is the dark primary colour). `branding clear-logo` removes it.
+
+## Alternatives
+
+- **Whole-config rollout (`config apply`).** The theme round-trips through the config
+  snapshot's `tenant.branding` block and the files through `tenant.brandingAssets`, so
+  `config export → edit → apply` (or `apply --from env:staging` onto prod) carries the
+  complete brand, bytes included — but it re-plans the *entire* tenant config, so prefer
+  it when branding rides along with other config changes or moves between environments.
+  To swap a file in a snapshot, replace `branding/<slot>.<ext>` and keep its `path`: the
+  CLI re-hashes the file on disk. For a one-off change, `set-theme` / `set-logo` /
+  `set-font` are surgical.
+- **Admin UI.** A tenant admin (holding `administration.branding.manage`) edits the same
+  row live under **Administration → Branding**. Use it for quick per-tenant tweaks; use the CLI
+  for reproducible, cross-env rollout by a platform admin.
+
+## Gotchas
+
+- **Release gate:** a brand-new `plexus-cli branding` verb (or a new theme field) must be
+  live on the env before the CLI call resolves — otherwise the call fails with an unknown
+  function. Ask the platform operator whether the release is out.
+- `config export` names the logo and the font files by hash and writes their bytes to
+  `branding/`; `branding show` resolves their URLs (`logoUploads`, `fontUploads`). A
+  committing apply refuses a changed hash it has no bytes for
+  (`[branding/contentMissing]`), a font file that is not WOFF2 (`[branding/fontRefused]`)
+  and a font slot without an own family (`[branding/fontFamilyMissing]`).
+- `set-font` refuses (`INVALID`, German message) a slot without a saved
+  family, a family named like the back office's own fonts (`Inter Variable`, `Azeret Mono
+  Variable` — an `@font-face` is document-wide), anything over 2 MB and anything that is
+  not WOFF2 — convert TTF/OTF/WOFF first (e.g. `woff2_compress`).
+- Removing a family (config / `set-theme`) leaves its file attached but unused; the admin
+  page flags it. Clear the file with `branding clear-font` when you drop the family.
+- A deployment that once held external font URLs dropped them on upgrade (the platform
+  operator has the list of dropped URLs); re-upload those files with `set-font`.
+- Verify in the browser: DevTools → Network → the `.woff2` request from the Convex origin
+  answers 200 with `Access-Control-Allow-Origin: <the portal origin>` (fonts load
+  cross-origin; Convex storage reflects the requesting origin).
+- This is a live-DB operation; nothing else records it. A `config export` snapshot is
+  your only copy — keep it out of any shared or public place.
+
+## Related
+
+- [Update a tenant's config](./update-tenant-config.md) · [Onboard / establish a tenant](./onboard-tenant.md)
+- Command semantics: `plexus-cli branding <verb> --help`, `plexus-cli config apply --help`.

package/dist/skill/references/config/set-tenant-terms.md

@@ -0,0 +1,50 @@
+# Set a school's terms („Anmeldung" statt „Bewerbung")
+
+**When to use:** a school calls the process by another name — it runs an
+„Anmeldeverfahren", not a „Bewerbungsverfahren". One setting switches the whole product for that school: the UI,
+task titles, feed and party notes, applicant-name fallbacks, mail blocks and buttons,
+and every refusal the browser shows. URLs (`/e/units/<unit>/bewerben`) stay as they are.
+
+## What it is
+
+- `tenant.terms` in the tenant config — today one term: `application`, a **closed
+  choice**: `"Bewerbung"` (platform default) or `"Anmeldung"`. The browser and the
+  backend read the same rules, so both always say the same word.
+- Stored on `tenants.terms` **only when it deviates**. Absent = the platform's word.
+- An unknown term or choice is refused by `config set` / `config apply`
+  (`[terms/unknownTerm]`, `[terms/unknownChoice]`) — nothing silently falls back.
+- The person follows the choice: „Bewerber:in" → „Anmelder:in", „Bewerberportal" →
+  „Anmeldeportal".
+- Not rewritten: a school's own texts (letter deviations, offer/board labels, team
+  names — change those via `offer`/`config` as usual).
+
+## Set it (one command, dry-run first)
+
+```bash
+# dry run — prints the one-row plan
+plexus-cli --env staging config set --tenant <slug> --target tenant \
+  --key <slug> --field terms --value '{"application":"Anmeldung"}'
+# commit
+plexus-cli --env staging config set --tenant <slug> --target tenant \
+  --key <slug> --field terms --value '{"application":"Anmeldung"}' --confirm
+```
+
+Equivalent through a scratch export (a real tenant's config lives only in its
+deployment — keep the export private): `config export --tenant <slug> --out <scratch>/config.json` → set
+`"tenant": { …, "terms": { "application": "Anmeldung" } }` → `config apply --tenant
+<slug> --from snapshot:<scratch>/config.json` (dry run) → `--confirm`.
+
+Back to the platform word: `--value '{}'` (or remove the block and apply).
+
+## Verify
+
+- `plexus-cli --env <env> config export --tenant <slug>` shows `tenant.terms`.
+- Portal `https://<host>/<slug>/e` shows „Jetzt anmelden", nav „Anmelden", the
+  sign-in button „Einloggen"; the first server-rendered frame already says it (no flash).
+- Staff board: „Anmeldungen", „Anmeldung ablehnen", …
+
+## Gotchas
+
+- Texts the server **stored** before the switch (feed notes, party notes, task titles
+  already spawned) keep the word they were written with — history is not rewritten.
+- The portal's English UI is unaffected (terms are German words).