@quatronic/sdk 0.6.1-rc.4 → 0.7.0-rc.6

package/skills/qore-ship-checklist/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: qore-ship-checklist
+description: The quality gate to run before opening a pull request — translate the requirement into acceptance criteria, cover it with tests, get all automated checks green, and run an independent review. Use before committing a finished change or opening a PR.
+allowed-tools: Bash(pnpm:*), Bash(git add:*), Bash(git commit:*), Read, Edit
+---
+
+# Ship checklist
+
+Run this before opening a PR. It encodes Quatronic's definition of done.
+
+## 1. Acceptance criteria
+
+Restate the requirement as concrete, checkable acceptance criteria — what must
+be true for this to be "done". Keep them in the PR description.
+
+## 2. Tests for those criteria
+
+- **Unit** (`*.test.ts`) for pure logic and schemas — see /qore-add-feature.
+{{#if db}}- **Integration** (`*.integration.test.ts`) for anything whose behaviour lives
+  in the database (constraints, upserts, joins).{{#if auth}} Mirror
+  `src/features/profile/server/queries.integration.test.ts`; run with
+  `pnpm db:up` then `pnpm test:integration`.
+{{else}} Run with
+  `pnpm db:up` then `pnpm test:integration`.
+{{/if}}{{else}}- (No database module: integration tests apply once the app gains stateful behaviour.)
+{{/if}}- Write the test first where you can; watch it fail, then make it pass.
+
+## 3. All automated checks green
+
+```
+{{#if db}}pnpm db:generate && {{/if}}pnpm lint && pnpm format:check && pnpm typecheck && pnpm test:run && pnpm build
+```
+
+These are exactly what CI runs — `.github/workflows/ci.yml` calls Quatronic's
+shared pipeline, which invokes these same scripts. If any fail locally, the
+PR will be red — fix before pushing.
+
+{{#if db}}CI runs `pnpm db:generate` as a drift check and fails when it writes
+anything, so commit every migration it produces under `src/db/migrations`.
+
+{{/if}}Also check by hand (the automated gates don't catch everything): no
+third-party UI library imports, no `style={{ ... }}`, no raw/arbitrary color classes
+(`bg-blue-500`, `text-[#1234ff]`) — use semantic tokens
+(`text-destructive`, `bg-muted`, `border-border`) from `src/styles/theme.css`
+instead.
+
+If the change calls an external API, check after it deploys that the portal's
+Integrations tab lists every endpoint you call. One missing means its alias or
+path is not written as a literal at the call site — see
+/qore-add-integration step 4.
+
+## 4. Independent review
+
+- Run `/code-review` and resolve real findings.
+- {{#if auth}}Run `/security-review` — this app handles Keycloak sessions and per-user
+  data, so treat anything touching auth, roles, or user-scoped tables as
+  high-value.{{else}}Run `/security-review` — treat anything touching external input or
+  stored data as high-value.{{/if}} Resolve all critical/high findings before merge.
+{{#if auth=keycloak}}- Added or renamed a role? Say in the PR who should get it on staging and
+  production — nobody holds a new role there until someone grants it in the
+  portal's Access tab.
+{{/if}}
+
+## 5. Observability
+
+Walk the new code against `/qore-observability`:
+
+- Unexpected failures are left to throw (captured automatically, so no extra capture), no
+  error is swallowed without `Sentry.captureException`, and no capture of expected failures
+  (validation, not found, denied).
+- Business and audit events logged once with `Sentry.logger`; audit events carry
+  `qore.audit.event`{{#if auth}} (login/logout, authorization denials, mutations){{/if}}.
+- Custom attributes are `qore.*` and hold ids, never personal data or secrets.
+- No `console` in runtime code. `pnpm lint` is green.
+
+## 6. Commit & PR
+
+Small, focused commits on a feature branch. Open a PR (never push to
+`main`/`production` directly) so the change is reviewable, traceable, and
+revertable.

package/skills/qore-translate-strings/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: qore-translate-strings
+description: Add or change user-facing strings the bilingual (NL/EN) way — message keys in both catalogs, resolved with next-intl. Use whenever you write or edit visible copy.
+allowed-tools: Bash(pnpm:*), Edit, Read
+---
+
+# Translate strings
+
+This app is bilingual (Dutch + English) out of the box. Default locale is `nl`;
+the locale lives in a `locale` cookie (no `[locale]` in the URL). Never hardcode
+user-facing copy — every visible string is a key in `messages/nl.json` and
+`messages/en.json`.
+
+## Adding or changing a string
+
+1. Pick a namespace + key (e.g. `profile.displayName`). Reuse generic keys in
+   `common` (`save`, `saved`, `cancel`) instead of duplicating.
+2. Add the SAME key to BOTH `messages/nl.json` and `messages/en.json`. The
+   vitest parity test fails if the key sets differ.
+3. Use it:
+   - **Client or server component:** `const t = useTranslations("profile")` then
+     `t("displayName")`. (`useTranslations` works in both in next-intl v4.)
+   - **Dynamic / full-path key** (e.g. a value coming from a server action):
+     `const tRoot = useTranslations()` then `tRoot(fullKey)`.
+   - **Metadata / outside the render tree:** `getTranslations` from
+     `next-intl/server`.
+4. **Zod validation messages:** store the full message key as the zod message
+   (`.min(1, "profile.displayNameRequired")`) and resolve it where the form
+   shows `state.message` with a root translator. Mirror `src/features/profile/`.
+
+## Verify
+
+- `pnpm test:run` — runs the parity test (`src/i18n/messages.test.ts`).
+- `pnpm typecheck` — typed messages (`global.d.ts`) catch mistyped keys.
+
+Both run as part of /qore-ship-checklist.

package/skills/qore-use-addons/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: qore-use-addons
+description: Read the credentials of an addon (Postgres, Redis, object storage) that THIS module provisions in the portal. Use when your code needs to talk to a database, cache, or S3 bucket that you added to this module — covers the exact env-var names and how to read them.
+allowed-tools: Bash(pnpm:*), Edit, Read
+---
+
+# Use an addon
+
+An **addon** is infrastructure the portal provisions for *this* module — a
+Postgres database, a Redis cache, or an S3-compatible object store. You add it
+in the portal (the module's Resources tab); the portal then binds its
+credentials into the module's secret group for every environment, so the values
+land in `process.env` at runtime. You never copy a secret by hand.
+Adding or removing a resource also restarts the module automatically, so the
+env vars are live right away.
+
+The credentials arrive under **stable, addon-independent env-var names** (the
+portal aliases Northflank's raw keys to these). Read these names — not the
+`NF_*` keys you see in the Northflank dashboard:
+
+| Addon | Env var(s) your code reads |
+|-------|----------------------------|
+| **Postgres** | `DATABASE_URL` |
+| **Redis** | `REDIS_URL` |
+| **Object storage** (S3 / MinIO) | `S3_ENDPOINT`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY` |
+
+> These keys only exist once you've added the addon to this module in the
+> portal. Until then they're absent — that's why every read below fails fast
+> with a clear message instead of a mystery `undefined`.
+>
+> Need credentials for an addon owned by **another** module? That's a
+> connection, not an addon — use `/qore-add-connection` (the keys are
+> `CONN_<ALIAS>_*` and you read them via the SDK), not this skill.
+
+## 1. Declare the env keys
+
+Add the keys for the addons you use to the server schema in
+`src/config/env.ts`, so a missing binding is a clear startup error:
+
+```ts
+// inside serverSchema = z.object({ ... })
+  DATABASE_URL: z.string().min(1),            // Postgres
+  REDIS_URL: z.string().url(),                // Redis
+  S3_ENDPOINT: z.string().url(),              // Object storage
+  S3_ACCESS_KEY_ID: z.string().min(1),
+  S3_SECRET_ACCESS_KEY: z.string().min(1),
+```
+
+`DATABASE_URL` is already declared when this app was generated with a database.
+Add the others only for the addons you actually provisioned.
+
+## 2. Postgres — use the existing client
+
+{{#if db}}The database client already reads `DATABASE_URL` for you. Don't build a new
+pool; use the shared one:
+
+```ts
+import { getDb } from "@/lib/db"
+
+const db = getDb() // Drizzle over a lazily-created pg.Pool on DATABASE_URL
+```
+
+To add a table, use `/qore-add-db-table`.
+{{else}}(This app has no Postgres module — if you add the Postgres addon here, read it
+via `DATABASE_URL` with your own client.)
+{{/if}}
+
+## 3. Redis
+
+Install a client (`pnpm add ioredis`), then connect lazily — never at module
+scope, or `next build` (which imports modules without runtime env) breaks:
+
+```ts
+// src/lib/redis.ts
+import Redis from "ioredis"
+import { serverEnv } from "@/config/env"
+
+let _redis: Redis | undefined
+
+export function getRedis(): Redis {
+  if (!_redis) _redis = new Redis(serverEnv().REDIS_URL)
+  return _redis
+}
+```
+
+**Before you can run this locally**, `REDIS_URL` doesn't exist yet — the
+generator can't scaffold it into `.env.example` because the addon is added
+later, in the portal. Do this now, not as an afterthought:
+
+- Run a Redis yourself (e.g. `docker run -p 6379:6379 redis`), then add
+  `REDIS_URL=redis://localhost:6379` to `.env.local`.
+- Or, if you won't run one locally, declare the key as `.optional()` in
+  `env.ts` and guard the code path instead — the schema is all-or-nothing, so
+  a *required* key that's absent locally crashes every `serverEnv()` call,
+  not just the addon feature.
+
+## 4. Object storage (S3 / MinIO)
+
+The store is S3-compatible, so use the AWS SDK pointed at `S3_ENDPOINT`
+(`pnpm add @aws-sdk/client-s3`). MinIO needs `forcePathStyle: true`:
+
+```ts
+// src/lib/storage.ts
+import { CreateBucketCommand, S3Client } from "@aws-sdk/client-s3"
+import { serverEnv } from "@/config/env"
+
+// The MinIO addon is exclusive to this module+environment and ships WITHOUT a
+// bucket, so we create one on first use under a fixed name. No S3_BUCKET env
+// var exists or is needed.
+export const BUCKET = "app"
+
+let _s3: S3Client | undefined
+let _ensured: Promise<void> | undefined
+
+export function getS3(): S3Client {
+  if (!_s3) {
+    const env = serverEnv()
+    _s3 = new S3Client({
+      endpoint: env.S3_ENDPOINT,
+      region: "us-east-1", // ignored by MinIO, required by the SDK
+      forcePathStyle: true,
+      credentials: {
+        accessKeyId: env.S3_ACCESS_KEY_ID,
+        secretAccessKey: env.S3_SECRET_ACCESS_KEY,
+      },
+    })
+  }
+  return _s3
+}
+
+export function ensureBucket(): Promise<void> {
+  if (!_ensured) {
+    _ensured = getS3()
+      .send(new CreateBucketCommand({ Bucket: BUCKET }))
+      .then(() => undefined)
+      .catch((err: unknown) => {
+        const name = (err as { name?: string })?.name
+        if (name === "BucketAlreadyOwnedByYou" || name === "BucketAlreadyExists") return
+        _ensured = undefined // allow retry on a real failure
+        throw err
+      })
+  }
+  return _ensured
+}
+```
+
+Await `ensureBucket()` before the first storage operation, then use the fixed
+bucket:
+
+```ts
+import { PutObjectCommand } from "@aws-sdk/client-s3"
+import { BUCKET, ensureBucket, getS3 } from "@/lib/storage"
+
+await ensureBucket()
+await getS3().send(new PutObjectCommand({ Bucket: BUCKET, Key: key, Body: body }))
+```
+
+**Before you can run this locally**, same story as Redis — `S3_ENDPOINT` /
+`S3_ACCESS_KEY_ID` / `S3_SECRET_ACCESS_KEY` aren't in `.env.example`. Run a
+MinIO yourself (e.g. `docker run -p 9000:9000 quay.io/minio/minio server /data`) and
+add the three keys to `.env.local`, or declare them `.optional()` and guard
+the code path if you won't run one locally.
+
+## Local development recap
+
+{{#if db}}- **Postgres** — `pnpm dev` uses the Postgres from `docker compose up -d`;
+  `DATABASE_URL` is already in `.env.example`.
+{{/if}}- **Redis / object storage** — see the "before you can run this locally" note
+  in steps 3/4 above — set the matching keys in `.env.local`, they are not
+  scaffolded for you.
+
+## Ship it
+
+Run the full local check loop — `pnpm lint && pnpm typecheck && pnpm test:run &&
+pnpm build` — then `/qore-ship-checklist` before a PR.

package/skills/qore-use-database/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: qore-use-database
+description: How this module's Postgres database works — where DATABASE_URL comes from, running the database locally, adding a client (pg or Drizzle), and applying migrations. Use when reading or writing data, adding a table, or debugging a connection error.
+allowed-tools: Bash(pnpm:*), Bash(docker:*), Read, Edit, Write
+---
+
+# Using this module's database
+
+This module owns a Postgres database. The platform provisions it and injects the
+connection string; the module brings its own client. Nothing is pre-wired — this
+skill is the whole contract.
+
+## 1. Where `DATABASE_URL` comes from
+
+`src/config/env.ts` requires `DATABASE_URL` (`z.string().min(1)`), so the service
+refuses to boot without it.
+
+| Where | How it arrives |
+|-------|----------------|
+| **Local** | `pnpm bootstrap` (or `qore env pull`) fetches it from the portal into `.env`. It points at the docker-compose database below on this module's own port: `postgresql://postgres:postgres@localhost:<DB_PORT>/app`, with `DB_PORT` written alongside it |
+| **staging / prod** | The portal injects the Northflank Postgres addon's own connection string per environment. Different host, database and credentials than local — never assume the local values. |
+
+Rules: never hardcode a connection string, never commit `.env` (it is gitignored),
+never read `process.env.DATABASE_URL` directly — import `env` from
+`./config/env.js` so a missing value fails fast at boot instead of at first query.
+
+If `pnpm dev` dies on `DATABASE_URL: Required`, your `.env` is stale: re-run
+`qore env pull` (or `qore run -- pnpm dev` to skip the file).
+
+## 2. Running the database locally
+
+```
+pnpm db:up      # start Postgres (docker compose up -d)
+pnpm db:down    # stop it, keep the data
+pnpm db:reset   # destroy the volume and start clean
+```
+
+`docker-compose.yml` creates database `app` with user/password `postgres`.
+`pnpm bootstrap` already runs `db:up`. The host port is `DB_PORT` from `.env`:
+the portal assigns each module its own, so two modules with a database never
+fight over a port. `ECONNREFUSED 127.0.0.1:<DB_PORT>` usually
+means the container is not running — `pnpm db:up` — but `db:up` is `docker
+compose up -d` with no health wait, so the same error is also normal for a
+second or two right after starting; check `docker compose ps` / the compose
+healthcheck, or just retry.
+
+Don't change `DB_PORT` or the port in `DATABASE_URL` by hand: both are
+portal-managed, and `qore env pull` overwrites them with the assigned values.
+If the port is taken anyway, something else is listening on it — stop that, or
+ask for the module's local ports to be reassigned in the portal.
+
+A psql shell into the running container:
+
+```
+docker compose exec db psql -U postgres -d app
+```
+
+## 3. Adding a client
+
+Pick one and stay with it. Both are traced automatically: the SDK's Sentry
+register instruments `pg`, so every query becomes a span — Drizzle included.
+
+### Option A — `pg` (default: no ORM, plain SQL)
+
+```
+pnpm add pg && pnpm add -D @types/pg
+```
+
+Create `src/lib/db.ts` — one pool per process, created at module load;
+connections are opened on demand as queries need them. Never open a client
+per request:
+
+```ts
+import { Pool, type QueryResultRow } from "pg"
+import { resolvePostgresConfig } from "@quatronic/sdk/node/db"
+import { env } from "../config/env.js"
+
+// One pool per process. Never configure `ssl` by hand here — always spread
+// resolvePostgresConfig(): it owns the TLS decision (no TLS for local
+// docker-compose, encrypted-but-unverified for Northflank's managed Postgres,
+// which terminates TLS with its own private CA, and full certificate
+// verification for any external database) and it strips the ssl params out of
+// the URL, without which `pg` silently overrides whatever `ssl` you pass —
+// it parses the connection string after the client options.
+const pool = new Pool({ ...resolvePostgresConfig(env.DATABASE_URL), max: 10 })
+
+export function query<T extends QueryResultRow>(
+  sql: string,
+  params: unknown[] = [],
+): Promise<T[]> {
+  return pool.query<T>(sql, params).then((r) => r.rows)
+}
+
+/** Run several statements on one connection inside a transaction. */
+export async function transaction<T>(fn: (c: import("pg").PoolClient) => Promise<T>): Promise<T> {
+  const client = await pool.connect()
+  try {
+    await client.query("BEGIN")
+    const out = await fn(client)
+    await client.query("COMMIT")
+    return out
+  } catch (err) {
+    await client.query("ROLLBACK")
+    throw err
+  } finally {
+    client.release()
+  }
+}
+
+export function closePool(): Promise<void> {
+  return pool.end()
+}
+```
+
+Always parameterise — `query("select * from widgets where id = $1", [id])`.
+String-interpolating a value into SQL is an injection bug; there are no
+exceptions to this.
+
+Close the pool on shutdown, in `src/index.ts`:
+
+```ts
+import { closePool } from "./lib/db.js"
+
+process.on("SIGTERM", () => {
+  server.close(() => {
+    void closePool().finally(() => process.exit(0))
+  })
+})
+```
+
+### Option B — Drizzle (typed schema + generated migrations)
+
+```
+pnpm add drizzle-orm pg && pnpm add -D drizzle-kit @types/pg tsx
+```
+
+Then follow the frontend convention: `src/db/schema.ts` defines tables on
+`pgSchema("app")`, `drizzle.config.ts` points `out` at `src/db/migrations`, and
+`drizzle-kit generate` writes the SQL. Commit the generated SQL and `meta/` and
+never hand-edit them — change `schema.ts` and regenerate.
+
+Drizzle runs on a `pg` pool, so build it exactly like option A —
+`new Pool({ ...resolvePostgresConfig(env.DATABASE_URL), max: 10 })` — and pass
+that pool to `drizzle()`. The same rule applies: never set `ssl` yourself.
+
+If the service dies at boot with `Error: self-signed certificate`, this is what
+was skipped: something is verifying Northflank's private CA, which can never
+succeed.
+
+## 4. Migrations
+
+There is no migration runner in this module; that is deliberate — you choose the
+tool. Whatever you pick, the rules are the same:
+
+- Migrations are **files in the repo**, applied automatically at boot. Do not
+  create tables by hand in a psql shell: staging and prod have databases you
+  cannot reach.
+- Forward-only. Never edit a migration that has already run in an environment —
+  add a new one.
+
+Minimal plain-SQL runner if you took option A. Add `src/db/migrations/0001_init.sql`,
+then `src/lib/migrate.ts`:
+
+```ts
+import { readdir, readFile } from "node:fs/promises"
+import { join } from "node:path"
+import * as Sentry from "@sentry/node"
+import { transaction } from "./db.js"
+
+// dist/lib/migrate.js runs from dist/, and tsc never copies .sql files — the
+// build script must copy src/db/migrations into dist/db/migrations, e.g.:
+//   "build": "tsc -p tsconfig.json && cp -R src/db/migrations dist/db/migrations"
+// Without that step this throws ENOENT, in local dev (`pnpm dev`/`pnpm start`
+// run dist/) and in the container alike (the Dockerfile copies dist/ wholesale).
+const MIGRATIONS_DIR = join(import.meta.dirname, "../db/migrations")
+
+export async function runMigrations(): Promise<void> {
+  const files = (await readdir(MIGRATIONS_DIR)).filter((f) => f.endsWith(".sql")).sort()
+  await transaction(async (client) => {
+    // Serialise concurrent boots (two replicas start at once) on one advisory
+    // lock, taken BEFORE the table it protects — otherwise two replicas can
+    // still race the create-table statement itself.
+    await client.query("select pg_advisory_xact_lock(hashtext('schema_migrations'))")
+    await client.query(
+      "create table if not exists schema_migrations (name text primary key, applied_at timestamptz not null default now())",
+    )
+    const { rows } = await client.query<{ name: string }>("select name from schema_migrations")
+    const applied = new Set(rows.map((r) => r.name))
+    for (const name of files.filter((f) => !applied.has(f))) {
+      await client.query(await readFile(join(MIGRATIONS_DIR, name), "utf8"))
+      await client.query("insert into schema_migrations (name) values ($1)", [name])
+      Sentry.logger.info("migration applied", { "qore.migration.name": name })
+    }
+  })
+}
+```
+
+This runner wraps *all* pending migrations in a single transaction, so a
+statement that cannot run inside a transaction block (e.g. `CREATE INDEX
+CONCURRENTLY`, or `ALTER TYPE … ADD VALUE` on older Postgres versions) will
+fail. Such a migration needs to run outside the shared transaction — give it
+its own connection/transaction rather than adding it to the loop above.
+
+Call it in `src/index.ts` **before** `server.listen` and let a failure crash the
+process — a service running against an unmigrated database is worse than one that
+does not start:
+
+```ts
+await runMigrations()
+server.listen(env.PORT, () => { /* ... */ })
+```
+
+## 5. Sharing this database with another module
+
+Do not hand your `DATABASE_URL` to another module. The portal models this as a
+connection: the consumer gets `CONN_<ALIAS>_URI` / `_HOST` / `_USER` / … for your
+resource. See the `qore-add-connection` skill.
+
+## 6. Before you ship
+
+`pnpm lint && pnpm typecheck && pnpm test:run && pnpm build`, and check that a fresh clone works:
+`pnpm db:reset && pnpm bootstrap && pnpm build && pnpm dev`.

package/skills/qore-use-design-system/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: qore-use-design-system
+description: Use this app's house component kit and design tokens. Use whenever building or restyling UI — pages, forms, tables, dialogs — so the app stays visually consistent.
+---
+
+# Use the design system
+
+This app ships a house component kit in `src/components/ui/` (built on shadcn/ui
++ Radix primitives) and a token canon in `src/styles/theme.css`. Build UI on
+top of it instead of reaching for raw colors or one-off markup.
+
+## Rules
+
+1. **Import UI from `@/components/ui`** — the barrel — never a deep path like
+   `@/components/ui/Button`. (`eslint-plugin-no-restricted-imports` enforces
+   this: only the kit's own files are exempt.) Never import a UI library
+   directly in pages/features either.
+2. **Use canon tokens only.** The semantic set from `theme.css`: `background`/
+   `foreground`, `card`(+`-foreground`), `popover`(+`-foreground`), `primary`
+   (+`-foreground`), `secondary`(+`-foreground`), `muted`(+`-foreground`),
+   `accent`(+`-foreground`), `destructive`(+`-foreground`), `border`, `input`,
+   `ring`, `radius` — e.g. `bg-card`, `text-muted-foreground`,
+   `border-border`. Never raw palette colors (`text-red-500`, `bg-[#...]`) and
+   never the `style={{}}` prop — both are ESLint errors. Layout/spacing
+   utilities (`flex`, `gap-4`, `p-6`, …) are fine everywhere.
+3. **Reach for layout primitives first** — `PageContainer`, `PageHeader`,
+   `PageHero`, `EmptyState`, `ErrorState`, `LoadingState`, `SectionCard` —
+   before composing something new.
+4. **Re-theme by editing `src/styles/theme.css`** — the single swap-point
+   (`:root` + `.dark`) — not by touching component internals or sprinkling
+   colors into features.
+5. **Feature-specific tokens** (status colors, severity, etc.) go in a
+   co-located `tokens.ts`, imported — never duplicated inline.
+
+## Missing a component?
+
+If the kit lacks a wrapper you need, add it to `src/components/ui/` in the
+same thin-wrapper style (with a co-located `*.test.tsx`) and export it from
+`index.ts` — don't drop a raw UI library import into a feature. The kit is
+yours to grow; keep features importing only from the barrel.
+
+## React-Aria-style compat props
+
+Several components preserve React-Aria-style prop names on top of their
+native/Radix API for continuity: `onPress`, `isDisabled`, `isLoading`,
+`isInvalid`, `isRequired`, `onSelectionChange`, `isOpen`/`onOpenChange`. Prefer
+these where a component supports them instead of mixing in native DOM handler
+names.
+
+Note the split on overlays: `Modal` is controlled via `isOpen`/`onOpenChange`,
+while `Sheet` uses Radix's native `open`/`onOpenChange` — don't mix them up.
+
+## Available components
+
+Form/controls: `Button` · `Field`/`Input`/`Textarea` · `Select` · `Checkbox`/
+`CheckboxGroup` · `SearchInput` · `FilterPills`.
+
+Data display: `Badge` · `StatCard` · `DataTable`/`DataRow` · `Table` · `Tabs` ·
+`Card`/`CardHeader`/`CardFooter`/`CardTitle`/`CardAction`/`CardDescription`/
+`CardContent` · `Avatar`/`AvatarImage`/`AvatarFallback` · `Skeleton` ·
+`Spinner` · `Link`.
+
+Overlays: `Modal` · `Sheet` (+ `SheetTrigger`/`SheetClose`/`SheetContent`/
+`SheetHeader`/`SheetFooter`/`SheetTitle`/`SheetDescription`) · `DropdownMenu`
+(+ `DropdownMenuTrigger`/`Content`/`Group`/`Label`/`Item`/`CheckboxItem`/
+`RadioGroup`/`RadioItem`/`Separator`/`Shortcut`/`Sub`/`SubTrigger`/
+`SubContent`/`Portal`) · `Popover` (+ `PopoverAnchor`/`PopoverContent`/
+`PopoverDescription`/`PopoverHeader`/`PopoverTitle`/`PopoverTrigger`) ·
+`Tooltip` (+ `TooltipProvider`/`TooltipRoot`/`TooltipTrigger`/
+`TooltipContent`).
+
+Layout: `PageContainer` · `PageHeader` · `PageHero` · `SectionCard` ·
+`EmptyState` · `ErrorState` · `LoadingState`.
+
+All exported from `src/components/ui/index.ts` — check there for the
+authoritative, up-to-date list.

package/skills/qore-use-mail-domain/SKILL.next.md

@@ -0,0 +1,67 @@
+---
+name: qore-use-mail-domain
+description: Send email through a mail domain linked to this module in the portal, using MAIL_API_KEY/MAIL_SENDING_DOMAIN/MAIL_FROM. Use when this app needs to send its own business email (notifications, receipts, alerts) — not auth email, which next-betterauth already handles separately.
+allowed-tools: Bash(pnpm:*), Edit, Read
+---
+
+# Use a linked mail domain
+
+A **mail domain** is a sending domain the tenant links to *this* module in the
+portal (Module → Mail tab — pick a sending domain, a local part, and a sender
+name). Linking pushes three env vars into this module's `stag`/`prod`
+environments:
+
+| Env var | What it is |
+|---------|------------|
+| `MAIL_API_KEY` | a domain-scoped token for sending mail |
+| `MAIL_SENDING_DOMAIN` | the domain, e.g. `acme.nl` — informational only, already baked into `MAIL_FROM` |
+| `MAIL_FROM` | the full from-header, e.g. `Acme Support <support@acme.nl>` |
+
+> These are system-managed: they never appear in `.env.example`, never show up
+> in this module's Secrets tab, and you cannot set them yourself. Until a
+> domain is linked they're simply absent.
+
+## Hard rule: never present in `local` or preview
+
+Unlike an addon (Redis, S3 — see `/qore-use-addons`) there is no way to
+stand up a real sending domain on your laptop or in a preview deploy.
+`MAIL_*` is **pushed into every deployed environment (today: `stag` and
+`prod`) — never `local`, never preview**. Don't go looking for a way to test
+a real send outside deployed environments — `sendMail` already handles this
+by falling back to a warning log, and that fallback is correct behaviour,
+not a placeholder to replace later.
+
+## Send mail
+
+Use `sendMail` from `src/lib/mail.ts`:
+
+```ts
+import { sendMail } from "@/lib/mail"
+
+await sendMail({
+  to: user.email,
+  subject: "Your export is ready",
+  html: "<p>...</p>",
+  text: "...",
+})
+```
+
+It reads `MAIL_API_KEY`/`MAIL_FROM` from `process.env` and calls Resend's send
+API. When `MAIL_API_KEY` is absent it logs `mail skipped` via
+`Sentry.logger.warn` (no recipient, subject or body) and returns, so
+local/preview dev works without a real domain.
+
+Worked example: `docs/examples/mail.example.ts`.
+
+## This is not auth email
+
+If this app has Better Auth (`next-betterauth`), verification and magic-link
+email already flow through `src/lib/email/send.ts` and its own
+`RESEND_API_KEY`/`EMAIL_FROM` — a separate mechanism tied to the portal's
+platform sender, not to a per-module linked domain. Don't merge the two;
+`sendMail` here is for this module's own business email.
+
+## Ship it
+
+Run the full local check loop — `pnpm lint && pnpm typecheck && pnpm test:run
+&& pnpm build` — then `/qore-ship-checklist` before a PR.