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

package/skills/catalog.json

@@ -0,0 +1,24 @@
+{
+  "skills": [
+    {"name": "qore-add-api-route", "kind": "convenience", "requires": ["runtime=next"], "legacyNames": ["quatronic-add-api-route"]},
+    {"name": "qore-add-connection", "kind": "contract", "legacyNames": ["quatronic-add-connection"]},
+    {"name": "qore-add-db-table", "kind": "convenience", "requires": ["runtime=next", "db"], "legacyNames": ["quatronic-add-db-table"]},
+    {"name": "qore-add-feature", "kind": "convenience", "requires": ["runtime=next"], "legacyNames": ["quatronic-add-feature"]},
+    {"name": "qore-add-integration", "kind": "contract", "legacyNames": ["quatronic-add-integration"]},
+    {"name": "qore-add-page", "kind": "convenience", "requires": ["runtime=next"], "legacyNames": ["quatronic-add-page"]},
+    {"name": "qore-author-skill", "kind": "convenience", "legacyNames": ["quatronic-author-skill"]},
+    {"name": "qore-debug-issue", "kind": "convenience"},
+    {"name": "qore-enable-auth-method", "kind": "convenience", "requires": ["auth=betterauth"], "legacyNames": ["quatronic-enable-auth-method"]},
+    {"name": "qore-observability", "kind": "contract", "legacyNames": ["quatronic-observe"]},
+    {"name": "qore-recommended-tools", "kind": "convenience", "requires": ["runtime=next"], "legacyNames": ["quatronic-recommended-tools"]},
+    {"name": "qore-secure-io", "kind": "convenience", "requires": ["runtime=next"], "legacyNames": ["quatronic-secure-io"]},
+    {"name": "qore-ship-checklist", "kind": "convenience", "requires": ["runtime=next"], "legacyNames": ["quatronic-ship-checklist"]},
+    {"name": "qore-translate-strings", "kind": "convenience", "requires": ["runtime=next"], "legacyNames": ["quatronic-translate-strings"]},
+    {"name": "qore-use-addons", "kind": "convenience", "requires": ["runtime=next"], "legacyNames": ["quatronic-use-addons"]},
+    {"name": "qore-use-database", "kind": "contract", "requires": ["runtime=node", "db"], "legacyNames": ["quatronic-use-database"]},
+    {"name": "qore-use-design-system", "kind": "convenience", "requires": ["runtime=next"], "legacyNames": ["quatronic-use-design-system"]},
+    {"name": "qore-use-mail-domain", "kind": "convenience", "legacyNames": ["quatronic-use-mail-domain"]},
+    {"name": "qore-use-permissions", "kind": "contract", "requires": ["auth=keycloak"], "legacyNames": ["quatronic-use-permissions"]},
+    {"name": "qore-verify-user", "kind": "convenience", "requires": ["runtime=node"], "legacyNames": ["quatronic-verify-user"]}
+  ]
+}

package/skills/qore-add-api-route/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: qore-add-api-route
+description: Add a business HTTP route under src/app/api/ for external callers{{#if auth}}, protected with the SDK{{/if}}. Use for API endpoints — internal mutations are Server Actions, not routes.
+allowed-tools: Bash(pnpm:*), Edit, Read
+---
+
+{{#if auth}}> Gating access by role/permission? See /qore-use-permissions.{{#if auth=keycloak}} Added a role key? Run `qore roles sync` yourself, then ask before `qore roles use` (§3 there).{{/if}}
+
+
+{{/if}}# Add an API route
+
+Internal mutations use Server Actions (see /qore-add-feature). Use an API
+route only for **external** callers.
+
+1. Create `src/app/api/<name>/route.ts`, following the layout of the existing
+   routes — segment config first, then imports, then the handler:
+{{#if auth}}   ```ts
+   export const runtime = "nodejs"
+   export const dynamic = "force-dynamic" // set for any non-trivial handler (POST, reads request, must not be cached)
+
+   import { NextResponse } from "next/server"
+   import { getRequireAuth } from "@/lib/auth"
+
+   export async function GET() {
+     const requireAuth = await getRequireAuth()
+     const user = await requireAuth()
+     return NextResponse.json({ id: user.id })
+   }
+   ```
+{{else}}   ```ts
+   export const runtime = "nodejs"
+   export const dynamic = "force-dynamic" // set for any non-trivial handler
+
+   import { NextResponse } from "next/server"
+
+   export async function GET() {
+     return NextResponse.json({ ok: true })
+   }
+   ```
+   (No auth module is installed — protect external routes with your own token
+   check or add auth via the portal before exposing sensitive data.)
+{{/if}}
+2. Keep data access in a feature slice's `server/` dir, not inline in the route.
+
+> API responses are data, not localized UI, so they generally need no
+> translation. If a route returns human-readable text meant for end users,
+> treat it like any UI string (see /qore-translate-strings).
+
+3. Let unexpected failures throw — they are captured automatically. Use
+   `Sentry.captureException(err, { tags })` only for a failure you handle that
+   should never happen, never for expected ones (validation, not found, denied).
+   Add a `Sentry.logger.info` line for the business event (no PII); request
+   tracing is automatic. See /qore-observability.
+4. Run the full local check loop — `pnpm lint && pnpm typecheck && pnpm test:run
+   && pnpm build` — then /qore-ship-checklist before a PR.
+
+{{#if auth}}> Never touch the auth catch-all (`src/app/api/auth/[...qdc]/route.ts`) — it is SDK-owned.
+{{/if}}

package/skills/qore-add-connection/SKILL.next.md

@@ -0,0 +1,149 @@
+---
+name: qore-add-connection
+description: Wire a module-to-module connection — declare its env, guard an incoming route with requireConnection, call out with connection().fetch, and fail-fast at startup with assertConnection. Use when this app talks to another Quatronic module.
+allowed-tools: Bash(pnpm:*), Edit, Read
+---
+
+# Add a connection
+
+A connection links two Quatronic modules. The portal injects the env on both
+sides when the connection is wired (`CONN_<ALIAS>_URL`, `CONN_<ALIAS>_TOKEN` for
+a service; `CONN_<ALIAS>_URI`/`_HOST`/… for a resource). `<ALIAS>` is the
+provider slug uppercased, non-alphanumerics collapsed to `_`. The SDK reads only
+this env — it never calls the portal at runtime.
+
+> A single-module app has no connections. Only follow this once the portal shows
+> a wired connection for this module (its env keys exist in the Secrets tab).
+
+## Kinds of connection
+
+`connection(alias)` returns one handle with four methods — which one you call
+depends on what the alias was wired to in the portal:
+
+- **`.fetch(path, init?)`** — the alias is another **module** (a service
+  connection). This is module-to-module talking directly over the network via
+  its own API, authenticated with a shared-secret token in the
+  `X-QDC-Connection-Token` header. No addon involved.
+- **`.postgres()` / `.redis()` / `.s3()`** — the alias is a **resource** (an
+  addon: Postgres, Redis, or object storage) this module was granted access
+  to. These return typed connection material (URI, host, credentials, …), not
+  an HTTP client — you pass it to your own DB/cache/S3 client.
+
+`assertConnection(alias, kind)` takes the matching `kind` too: `"service"` for
+`.fetch()`, `"postgres"`/`"redis"`/`"s3"` for the resource accessors.
+`requireConnection` (step 4) is provider-side only — a resource connection has
+no inbound side, so it's only ever used for service connections.
+
+## 1. Declare the connection's env (consumer side only)
+
+**Only do this when THIS module calls out** via `.fetch()`/`.postgres()`/
+`.redis()`/`.s3()` (steps 2-3). If this module is only the **provider** guarding
+an inbound route (step 4), skip this step entirely — see the note there.
+
+Add the keys to the server schema in `src/config/env.ts` so a missing wire is a
+clear startup error, not a mystery 500. For a service connection to `billing-api`
+(alias `BILLING_API`):
+
+```ts
+// inside serverSchema = z.object({ ... })
+  CONN_BILLING_API_URL: z.string().url(),
+  CONN_BILLING_API_TOKEN: z.string().min(1),
+```
+
+## 2. Fail-fast at startup
+
+In a module-scoped init path (e.g. a server-only module imported by your feature
+code), assert the wire once:
+
+```ts
+import { assertConnection } from "@quatronic/sdk/next/connections"
+import { serverEnv } from "@/config/env"
+
+assertConnection("billing-api", "service", { env: serverEnv() as Record<string, string> })
+```
+
+## 3. Call out to the other module
+
+```ts
+import { connection } from "@quatronic/sdk/next/connections"
+
+const res = await connection("billing-api").fetch("/invoices", { method: "GET" })
+// connection() reads process.env; the X-QDC-Connection-Token header is added
+// from CONN_BILLING_API_TOKEN automatically. Default 10s timeout.
+const invoices = await res.json()
+```
+
+For a resource connection, use the typed accessor instead of `.fetch`:
+
+```ts
+const { uri } = connection("main-db").postgres() // { uri, host?, port?, user?, password?, db? }
+const { url } = connection("cache").redis()
+const { endpoint, bucket, accessKey, secretKey } = connection("media").s3()
+```
+
+## 4. Guard an incoming connection route
+
+When THIS module is the provider, protect the receiving route. The guard is
+edge-safe, so it also works in `middleware.ts` to protect a whole route group.
+
+**No `env.ts` schema entry needed for this** — unlike step 1, `requireConnection`
+doesn't take or need an alias: it scans `process.env` for every `CONN_*_TOKEN`
+key present and matches the incoming request's token against all of them, so
+it works with whatever alias the portal happened to derive on the consumer's
+side. Also note the portal never gives a provider its own `CONN_<ALIAS>_URL` —
+only a consumer gets a `_URL` — so requiring `CONN_<ALIAS>_URL` in this
+module's `env.ts` when it's provider-only will always fail (crash-loop) since
+that key can never exist.
+
+```ts
+// src/app/api/internal/<name>/route.ts
+export const runtime = "nodejs"
+export const dynamic = "force-dynamic"
+
+import { NextResponse } from "next/server"
+import { requireConnection, ConnectionError } from "@quatronic/sdk/next/connections"
+
+export async function POST(req: Request) {
+  try {
+    const alias = await requireConnection(req) // returns the matched <ALIAS>
+    // ... handle the trusted request; `alias` tells you which consumer wired in
+    return NextResponse.json({ ok: true })
+  } catch (e) {
+    if (e instanceof ConnectionError) {
+      return NextResponse.json({ error: e.code }, { status: e.status })
+    }
+    throw e
+  }
+}
+```
+
+`requireConnection` is `async` (it uses Web Crypto for a constant-time token
+compare) — always `await` it. It throws `ConnectionError` with code `not_wired`
+/ `missing_token` / `invalid_token` (status 401).
+
+### Fail-fast that an inbound connection is wired (optional)
+
+To assert at startup that *some* connection is wired to this provider, use the
+alias-agnostic `assertInboundConnection` (the provider doesn't know its callers'
+aliases, so `assertConnection` from step 2 doesn't apply):
+
+```ts
+import { assertInboundConnection } from "@quatronic/sdk/next/connections"
+
+assertInboundConnection()
+// throws not_wired (500) if no CONN_*_TOKEN is present in process.env
+```
+
+Do **not** implement this by calling `requireConnection` with a tokenless
+`Request`. `requireConnection` always logs a `qore.connection.rejected` /
+`missing_token` warning before it throws, so a tokenless probe emits a
+misleading rejection on **every healthy boot**. `assertInboundConnection` reads
+the env directly and stays silent when a connection is wired.
+
+## 5. Ship it
+
+Run the full local check loop — `pnpm lint && pnpm typecheck && pnpm test:run &&
+pnpm build` — then /qore-ship-checklist before a PR.
+
+> A worked, non-wired reference lives at `src/examples/connection.example.ts`.
+> Don't hand-edit the auth/SDK boundary (`src/lib/auth.ts`, `src/proxy.ts`).

package/skills/qore-add-connection/SKILL.node.md

@@ -0,0 +1,160 @@
+---
+name: qore-add-connection
+description: Wire a module-to-module connection — declare its env, guard an incoming request with requireConnection, call out with connection().fetch, and fail-fast at startup with assertConnection. Use when this backend talks to another Quatronic module.
+allowed-tools: Bash(pnpm:*), Edit, Read
+---
+
+# Add a connection
+
+A connection links two Quatronic modules. The portal injects the env on both
+sides when the connection is wired (`CONN_<ALIAS>_URL`, `CONN_<ALIAS>_TOKEN` for
+a service; `CONN_<ALIAS>_URI`/`_HOST`/… for a resource). `<ALIAS>` is the
+provider slug uppercased, non-alphanumerics collapsed to `_`. The SDK reads only
+this env — it never calls the portal at runtime.
+
+> A single-module app has no connections. Only follow this once the portal shows
+> a wired connection for this module (its env keys exist in the Secrets tab).
+
+This module is a plain `node:http` service (no framework), so the provider side
+needs one small adapter — step 4 covers it.
+
+## Kinds of connection
+
+`connection(alias)` returns one handle with four methods — which one you call
+depends on what the alias was wired to in the portal:
+
+- **`.fetch(path, init?)`** — the alias is another **module** (a service
+  connection). This is module-to-module talking directly over the network via
+  its own API, authenticated with a shared-secret token in the
+  `X-QDC-Connection-Token` header. No addon involved.
+- **`.postgres()` / `.redis()` / `.s3()`** — the alias is a **resource** (an
+  addon: Postgres, Redis, or object storage) this module was granted access
+  to. These return typed connection material (URI, host, credentials, …), not
+  an HTTP client — you pass it to your own DB/cache/S3 client.
+
+`assertConnection(alias, kind)` takes the matching `kind` too: `"service"` for
+`.fetch()`, `"postgres"`/`"redis"`/`"s3"` for the resource accessors.
+`requireConnection` (step 4) is provider-side only — a resource connection has
+no inbound side, so it's only ever used for service connections.
+
+## 1. Declare the connection's env (consumer side only)
+
+**Only do this when THIS module calls out** via `.fetch()`/`.postgres()`/
+`.redis()`/`.s3()` (steps 2-3). If this module is only the **provider** guarding
+an inbound request (step 4), skip this step entirely — see the note there.
+
+Add the keys to the schema in `src/config/env.ts` so a missing wire is a clear
+startup error, not a mystery failure. For a service connection to `billing-api`
+(alias `BILLING_API`):
+
+```ts
+// inside `const schema = z.object({ ... })`
+  CONN_BILLING_API_URL: z.string().url(),
+  CONN_BILLING_API_TOKEN: z.string().min(1),
+```
+
+## 2. Fail-fast at startup
+
+In `src/index.ts`, before `server.listen(...)`, assert every wire this module
+declares:
+
+```ts
+import { assertConnection } from "@quatronic/sdk/node/connections"
+
+assertConnection("billing-api", "service") // reads process.env by default
+```
+
+## 3. Call out to the other module
+
+```ts
+import { connection } from "@quatronic/sdk/node/connections"
+
+const res = await connection("billing-api").fetch("/invoices", { method: "GET" })
+// connection() reads process.env; the X-QDC-Connection-Token header is added
+// from CONN_BILLING_API_TOKEN automatically. Default 10s timeout.
+const invoices = await res.json()
+```
+
+For a resource connection, use the typed accessor instead of `.fetch`:
+
+```ts
+const { uri } = connection("main-db").postgres() // { uri, host?, port?, user?, password?, db? }
+const { url } = connection("cache").redis()
+const { endpoint, bucket, accessKey, secretKey } = connection("media").s3()
+```
+
+## 4. Guard an incoming connection request
+
+When THIS module is the provider, protect the receiving handler.
+**No `env.ts` schema entry needed for this** — unlike step 1, `requireConnection`
+doesn't take or need an alias: it scans `process.env` for every `CONN_*_TOKEN`
+key present and matches the incoming request's token against all of them, so
+it works with whatever alias the portal happened to derive on the consumer's
+side. Also note the portal never gives a provider its own `CONN_<ALIAS>_URL` —
+only a consumer gets a `_URL` — so requiring `CONN_<ALIAS>_URL` in this
+module's `env.ts` when it's provider-only will always fail (crash-loop) since
+that key can never exist.
+
+`requireConnection` reads a Web-standard `Headers` object — `node:http` gives
+you a plain header map, so adapt it with `Headers` (already global in Node 18+):
+
+```ts
+// src/index.ts (or a handler module it dispatches to)
+import { requireConnection, ConnectionError } from "@quatronic/sdk/node/connections"
+import type { IncomingMessage, ServerResponse } from "node:http"
+
+function toWebHeaders(raw: IncomingMessage["headers"]): Headers {
+  const headers = new Headers()
+  for (const [key, value] of Object.entries(raw)) {
+    if (value === undefined) continue
+    headers.set(key, Array.isArray(value) ? value.join(", ") : value)
+  }
+  return headers
+}
+
+async function handleInbound(req: IncomingMessage, res: ServerResponse): Promise<void> {
+  try {
+    const alias = await requireConnection({ headers: toWebHeaders(req.headers) } as Request)
+    // ... handle the trusted request; `alias` tells you which consumer wired in
+    res.writeHead(200, { "content-type": "application/json" })
+    res.end(JSON.stringify({ ok: true, from: alias }))
+  } catch (e) {
+    if (e instanceof ConnectionError) {
+      res.writeHead(e.status, { "content-type": "application/json" })
+      res.end(JSON.stringify({ error: e.code }))
+      return
+    }
+    throw e
+  }
+}
+```
+
+`requireConnection` is `async` (it uses Web Crypto for a constant-time token
+compare) — always `await` it. It throws `ConnectionError` with code `not_wired`
+/ `missing_token` / `invalid_token` (status 401).
+
+### Fail-fast that an inbound connection is wired (optional)
+
+A provider-only module can assert at boot that *some* connection is wired to it.
+Because the provider doesn't know its callers' aliases, `assertConnection` (step
+2, alias-specific) doesn't apply — use the alias-agnostic `assertInboundConnection`:
+
+```ts
+// src/index.ts, before server.listen(...)
+import { assertInboundConnection } from "@quatronic/sdk/node/connections"
+
+assertInboundConnection() // throws not_wired (500) if no CONN_*_TOKEN is present
+```
+
+Do **not** implement this by calling `requireConnection` with a tokenless
+`Request`. `requireConnection` always logs a `qore.connection.rejected` /
+`missing_token` warning before it throws, so a tokenless probe emits a
+misleading rejection on **every healthy boot**. `assertInboundConnection` reads
+the env directly and stays silent when a connection is wired.
+
+## 5. Ship it
+
+Run `pnpm build` (type-checks and compiles) before a PR.
+
+> A worked, non-wired reference lives at `src/examples/connection.example.ts`.
+> The service is started by the SDK's Sentry register (`--import @quatronic/sdk/node/sentry/register`); don't change the start command.

package/skills/qore-add-db-table/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: qore-add-db-table
+description: Add a database table or column with Drizzle, including the migration. Use whenever a feature needs to persist new data, when a column is added to an existing table, and especially when a column will hold an id, slug or key of something that already exists somewhere (a user, an account, a spot, an order, a product) — the skill works out where that identifier comes from and records it. Use it even when the user only says "add a table", "store X per user" or "save which Y it belongs to". App tables live on the app schema; the SDK owns the auth schema.
+allowed-tools: Bash(pnpm:*), Edit, Read, Glob, Grep
+---
+
+# Add a DB table + migration
+
+1. Define the table in `src/db/schema.ts` on `appSchema = pgSchema("app")`
+   (the SDK owns the separate `auth` schema — never put app tables there):
+   ```ts
+   export const widgets = appSchema.table("widgets", {
+     id: uuid("id").primaryKey().defaultRandom(),
+     keycloakSub: text("keycloak_sub").notNull(),
+     name: text("name").notNull(),
+     createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+   })
+   export type Widget = typeof widgets.$inferSelect
+   export type NewWidget = typeof widgets.$inferInsert
+   ```
+2. For every column that identifies something — an id, a slug, a key, "who",
+   "which" — work out where it comes from before you write it. See
+   [Columns that identify something](#columns-that-identify-something) below.
+   This is the step that is easy to skip and expensive to skip.
+3. Generate the migration:
+   ```
+   pnpm db:generate
+   ```
+   This writes `src/db/migrations/NNNN_*.sql` and updates `meta/`. **Commit both.**
+4. Do NOT hand-edit generated SQL or `src/db/migrations/meta/`. To change a
+   table, edit `schema.ts` and re-run `pnpm db:generate`. (A *custom* migration
+   you create yourself for a cross-module reference is different — see below.)
+5. Migrations apply automatically at boot: `src/instrumentation.ts` calls
+   `runAppMigrations` (defined in `src/lib/migrate.ts`) — there is no separate
+   migrate command.
+6. Run the full local check loop — `pnpm lint && pnpm typecheck && pnpm test:run
+   && pnpm build` — then /qore-ship-checklist before a PR. To wire the
+   table into a form and Server Action, see /qore-add-feature.
+
+## Columns that identify something
+
+A column that holds an id, a slug or a key points at something, and that
+something often lives outside this table. Postgres only knows about the link
+when it is a foreign key inside this database. For every other case the
+knowledge is in your head now and nowhere later: `qore db erd` cannot draw the
+link, and the next developer cannot tell `account_id` from a random uuid.
+
+The user will rarely tell you where it comes from — to them "a spot" is just a
+spot. So look it up instead of guessing. Search for the *concept*, not only the
+literal word: "strand" is `spots`, "melding" is `sightings`, "wie" or "gebruiker"
+is the signed-in user. Three cases, checked in this order:
+
+1. **This database.** Grep this module's `src/db/schema.ts` for the table.
+   Found → a real foreign key: `uuid("spot_id").notNull().references(() => spots.id, { onDelete: "cascade" })`
+   (pick the delete rule the feature needs). This is the only case where Postgres
+   guards the link, so prefer it whenever the table is here.
+
+2. **The signed-in user.** "wie", "gebruiker", "account", "eigenaar", "created
+   by", "per user" — and no `accounts`/`users` table of our own anywhere in the
+   app → the identity is Keycloak's `sub`. Store it exactly as `user_profiles`
+   does: `keycloakSub: text("keycloak_sub").notNull()`, no foreign key (the IdP
+   owns it; tooling recognises this column by its name). Do not invent an
+   `account_id` uuid for this; there is no accounts table to point at.
+
+3. **Another module of this app.** The modules of an app are cloned side by side:
+   this module's siblings are the directories next to it, under the folder that
+   holds `qore.workspace.json`. Search them for the table or resource:
+   - Drizzle schemas: `*/src/db/schema.ts`
+   - plain SQL migrations: `*/src/db/migrations/*.sql`, `*/migrations/*.sql`
+   - API routes when a module has no database of its own: `*/src/api/routes.ts`,
+     `*/src/app/api/**/route.ts`
+   Also grep this module for `connection("<alias>")`: a value that arrives through
+   a connection is by definition from that module, and the alias names it.
+
+   Found → a **cross-module reference**: an ordinary column of the target's type
+   (uuid for an `id`, text for a slug) with the link declared next to it, so that
+   the database carries the knowledge. Follow
+   [references/cross-module-reference.md](references/cross-module-reference.md)
+   — it is a custom migration with one `COMMENT ON COLUMN`, not a foreign key,
+   because a foreign key cannot cross databases. Name the column after the
+   target's key (`spot_id` when the other module exposes ids, `spot_slug` when
+   its stable key is a slug).
+
+When a name exists both here and in a sibling (both the frontend and the backend
+have `sightings`), this module's own table wins unless the user clearly means the
+other one; say which one you took. When none of the three cases applies and the
+request does not say what the column identifies, ask one question and name the
+candidates you found — do not pick one silently.

package/skills/qore-add-db-table/references/cross-module-reference.md

@@ -0,0 +1,74 @@
+# Declaring a cross-module reference
+
+A column that stores the id (or slug) of a row that lives in another module's
+database cannot be a foreign key: Postgres cannot look into another database.
+The link still has to be recorded somewhere the database itself carries, so that
+`qore db erd` draws it, the next developer sees it, and it survives a rewrite of
+the application code. That place is a comment on the column.
+
+## The comment
+
+One line, starting with an arrow, then the module and the target:
+
+```
+-> <module-slug>:<schema>.<table>.<column>
+```
+
+- `<module-slug>` is the module as the portal knows it — the same name as the
+  connection alias (`connection("zeevonk-backend")` → `zeevonk-backend`) and as
+  the sibling directory in the workspace.
+- When the other module has no database and the thing is an API resource, point
+  at the endpoint and the field instead:
+  `-> zeevonk-backend:GET /beaches .slug`
+- Free text may follow the target, e.g. `(no FK: other database)`.
+
+Tooling reads only the part up to the first space after the target; keep it
+exact (`public.spots.id`, not `spots`).
+
+## Writing it: a custom migration
+
+Drizzle cannot express column comments (there is no `.comment()` on a column and
+`drizzle-kit generate` never emits `COMMENT ON`), so the comment goes into a
+migration you write yourself. That is not the same as hand-editing generated
+SQL: a custom migration is a separate journal entry that drizzle-kit creates for
+you and never touches again, and `pnpm db:generate` stays clean afterwards (the
+CI drift check keeps passing).
+
+Order matters: the column must exist before the comment can be set, so generate
+the schema migration first.
+
+```sh
+pnpm db:generate                                   # the column itself
+pnpm db:generate --custom --name=favourite_spots_spot_id_ref
+```
+
+The second command writes an empty `src/db/migrations/NNNN_favourite_spots_spot_id_ref.sql`
+and registers it in `meta/_journal.json`. Put the comment in that file:
+
+```sql
+COMMENT ON COLUMN "app"."favourite_spots"."spot_id" IS '-> zeevonk-backend:public.spots.id (no FK: other database)';
+```
+
+Commit the SQL file together with `meta/`. Migrations run at boot in journal
+order, so the comment lands right after the column.
+
+In `schema.ts`, give the column a short comment with the same target, so a reader
+of the code sees it without opening the migration:
+
+```ts
+// `spot_id` is `public.spots.id` in zeevonk-backend; no FK across databases.
+spotId: uuid("spot_id").notNull(),
+```
+
+## When the SDK provides `crossRef`
+
+Check whether `@quatronic/sdk/next/db` exports `crossRef`
+(`node_modules/@quatronic/sdk/dist/next/db/index.d.ts`). If it does, use it
+instead of the custom migration:
+
+```ts
+spotId: crossRef("spot_id", "zeevonk-backend", "public.spots.id").notNull(),
+```
+
+It defines the same uuid column and the SDK writes the comment at boot, right
+after the migrations. Until then, the custom migration above is the way.

package/skills/qore-add-feature/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: qore-add-feature
+description: Add a vertical feature slice (schema, server queries/mutations, server action, components){{#if auth}} mirroring src/features/profile/{{/if}}. Use when adding app functionality that has its own data and forms.
+allowed-tools: Bash(pnpm:*), Edit, Read
+---
+
+{{#if auth}}> Gating access by role/permission? See /qore-use-permissions.{{#if auth=keycloak}} Added a role key? Run `qore roles sync` yourself, then ask before `qore roles use` (§3 there).{{/if}}
+
+
+{{/if}}Import UI from `@/components/ui` (the house kit) — see the qore-use-design-system skill.
+
+# Add a feature slice
+
+A feature is a vertical slice: its own data access, server logic, and UI,
+under `src/features/<name>/`:
+
+```
+src/features/<name>/
+  components/   # feature-scoped React components
+  server/       # queries, mutations, server actions — this feature's data logic
+  hooks/        # feature-scoped React hooks
+  index.ts      # the feature's ONLY public surface
+```
+
+Not every feature needs all three subfolders — only create `components/`,
+`server/`, or `hooks/` if the feature actually has that kind of code.
+`index.ts` is required for every feature: other code (other features,
+`src/app/**`, `src/components/**`, …) may only import a feature through its
+`index.ts`, never by reaching into `components/`, `server/`, or `hooks/`
+directly. This is enforced by `eslint-plugin-boundaries`
+(`boundaries/no-private`, `allowUncles: false`) — see
+`src/features/README.md` for the full rule set, including:
+
+- `feature -> app` imports are forbidden (a feature must never import from
+  `src/app/**`).
+- `shared -> feature` and `shared -> app` are forbidden too — `src/{components,hooks,lib,config,styles,i18n}`
+  must stay free of feature- and app-specific knowledge.
+- Cross-feature access is only ever through the other feature's `index.ts`.
+
+{{#if auth}}Mirror `src/features/profile/`:
+{{else}}Create the slice under `src/features/<name>/` (this app starts without
+feature slices — this layout is the convention):
+{{/if}}
+
+- `schema.ts` — zod schemas for the feature's inputs.
+- `types.ts` — derived types + an action-state discriminated union
+  (`{ status: "idle" | "success" | "error", message?: string }`).
+{{#if db}}- `server/queries.ts` — Drizzle reads.
+- `server/mutations.ts` — Drizzle writes.
+{{else}}- `server/` — data access for the feature (no database module is installed; talk to your data source here).
+{{/if}}- `actions.ts` — `"use server"` entry points. {{#if auth}}Authenticate with
+  `getRequireAuth()` first, validate{{else}}Validate{{/if}} `FormData` with the zod schema via
+  `safeParse`, return the typed action-state union on failure, call a mutation,
+  then `revalidatePath(...)`. Server actions are traced automatically; let
+  unexpected failures throw.
+- `components/` — client components driving the actions with `useActionState`.
+- `index.ts` — re-export exactly what other code is allowed to use
+  (components, server actions, types — not raw queries/mutations unless
+  they're meant to be called directly).
+- All user-facing strings go through next-intl (`useTranslations`), with keys
+  in BOTH `messages/nl.json` and `messages/en.json` — see
+  /qore-translate-strings. Make zod validation messages message keys
+  (e.g. `"profile.displayNameRequired"`) and resolve them at the display site
+  with a root `useTranslations()` translator{{#if auth}}, mirroring `profile/`{{/if}}.
+
+{{#if db}}Add any new table to `src/db/schema.ts` on `appSchema = pgSchema("app")`, then
+`pnpm db:generate` and commit the generated migration (see
+/qore-add-db-table). {{/if}}Add a unit test next to the schema (`*.test.ts`) like
+{{#if auth}}`profile/schema.test.ts`{{else}}`<feature>/schema.test.ts`{{/if}}.
+
+Before you finish, walk the decision table in /qore-observability for each step of the feature.
+Most steps need nothing; add only what answers a production question.
+
+Finish with the full local check loop — `pnpm lint && pnpm typecheck &&
+pnpm test:run && pnpm build` — then run /qore-ship-checklist before opening
+a PR. Every feature needs a unit test for its schema/logic, and an integration
+test (`*.integration.test.ts`) when its behaviour is in the database.