pgkiln 0.31.0 → 0.36.0

package/docs/guide/08-security.md

@@ -47,10 +47,52 @@ The builder and the runtime cover what APEX offers for its accounts:
 The `meta.set_password`/`expire`/`unexpire` functions are owner-only. Grant them to an app role if
 you want to build user administration pages inside an application.
 
-pgkiln doesn't send e-mail, so there is no self-service "forgot password" link (APEX apps don't
-have one out of the box either). A user who forgot their password asks an administrator, who
-sets a temporary one under **Users → account → Set password**, with *Require change of password
-on first use* ticked (the default).
+A user who forgot their password asks an administrator, who sets a temporary one under
+**Users → account → Set password**, with *Require change of password on first use* ticked (the
+default), or uses **Forgot password?** when the application offers it (below).
+
+### Forgot password
+
+With **Application settings → Sign-in methods → Offer "Forgot password?"** the sign-in page (the
+built-in one or the application's [own login page](#the-login-page)) has a *Forgot password?* link
+(APEX apps don't have one out of the box). It needs an enabled [mail service](06-processing.md#sending-e-mail)
+with a From address for the application; without one the link isn't shown. It is for passwords
+of the user directory only: not for LDAP, single sign-on, database accounts or custom
+authentication.
+
+1. The user types their user name or e-mail address. The answer is always the same, whether or
+   not an account matched, so the page doesn't tell who has an account.
+2. An active account with a password and an e-mail address that may use the application gets an
+   e-mail (in the user's language) with a link to `/a/<alias>/password/reset?token=…`, built from
+   `PUBLIC_URL`, never from the request's `Host` header.
+3. The link works **once**, for **30 minutes**, in this application only. Opening it moves the
+   token into the session and out of the address bar; the user chooses a new password (the
+   [password policy](#passwords-and-my-account) applies).
+4. The new password ends every session and *Keep me signed in* token of the account, and makes
+   the account's other open links useless.
+
+Only a SHA-256 hash of each token is stored (`meta.password_reset`, owner only). Requests are
+limited to 5 per address in 15 minutes and 3 mails per account per hour; they count towards the
+application's daily mail limit and show in the activity log (`password_reset_request`,
+`password_reset`).
+
+### The login page
+
+`/a/<alias>/login` shows pgkiln's sign-in page: the application's name, the sign-in methods and,
+when the application has several languages, a language picker. To design your own (APEX: the
+login page, usually page 9999), choose **Application settings → Sign-in methods → Create a login
+page**: it adds page 9999 (or the next free number) that doesn't require authentication, with
+page template *Minimal (no navigation)* and a **Login** region, and makes it the application's
+**Login page**. From then on `/a/<alias>/login` (and every page that needs a signed-in user)
+sends visitors there.
+
+Edit it like any page: add static content, images, lists of links or any other region around the
+Login region, which is the sign-in form (identity providers, user name and password, *Keep me
+signed in*, *Forgot password?*). The form still posts to `/a/<alias>/login`, so throttling, the
+CSRF check and every sign-in method work as on the built-in page; a failed sign-in comes back to
+the login page with its message and the user name. A login page that requires authentication,
+or doesn't exist, is ignored (the built-in page shows) and the Advisor reports it; so does a
+login page without a Login region.
 
 With single sign-on, password changes happen at the identity provider; My account says so.
 
@@ -327,6 +369,16 @@ like for other users (an account of the same name, if there is one), or from the
 in authorization schemes. The login page has the user name and password form only: *Keep me signed
 in*, LDAP, single sign-on and the password-change form are not used by these apps.
 
+### Session timeout warning
+
+Sessions end after the idle time (`SESSION_IDLE_MINUTES`, or Instance settings) and at their maximum
+length (`SESSION_MAX_HOURS`). Signed-in users are warned before (Settings → *Errors and sessions* →
+*Session timeout warning*, default 120 seconds; 0: no warning; APEX: Session Timeout Warning): a
+dialog says when the session ends and offers **Stay signed in**, which marks the session active
+(POST `/a/<alias>/session/extend`, with the session's CSRF token). At the maximum length the user can
+only save their work; when the session has ended the dialog offers to sign in again and comes back
+to the page.
+
 ### Keep me signed in
 
 Under **Settings → Sign-in methods**, *"Keep me signed in" for (days)* (1–365) adds a checkbox to the

package/docs/guide/09-reference.md

@@ -13,6 +13,11 @@ triggers, your own functions).
 | `meta.jwt_claims()` | jsonb | The verified JWT claims of a PostgREST request, or NULL |
 | `meta.app_language()` | text | The language of the request (`nl`, `en-GB`, …) |
 | `meta.message(name, variadic params)` | text | A text message in the current language, `%0`…`%9` replaced; falls back to the base and primary language |
+| `meta.lang(text, language default null)` | text | A [dynamic translation](14-globalization.md#dynamic-translations) of a value from a table in the session's (or the given) language, else the text (APEX: `APEX_LANG.LANG`) |
+| `meta.get_app_setting(name)`, `meta.set_app_setting(name, value)` | text / void | An [application setting](06-processing.md#application-settings) of the current application (APEX: `APEX_APP_SETTING`); application code only |
+| `meta.get_preference(name, user default null)`, `meta.set_preference(name, value, user default null)`, `meta.remove_preference(name, user default null)` | text / void | A [user preference](06-processing.md#user-preferences) of the signed-in (or the given) user in the current application (APEX: `APEX_UTIL.*_PREFERENCE`) |
+| `meta.data_export(query, format default 'csv', options jsonb default '{}')` | bytea | A query's rows as a CSV, JSON, XML or HTML file, run with the caller's privileges ([data export](06-processing.md#data-export-from-sql); APEX: `APEX_DATA_EXPORT`) |
+| `meta.csv_field(value, separator default ',', is_text default true)` | text | One CSV field: quoted when needed, a formula neutralised |
 | `meta.password_days_left(username)` | int | Days until the password expires (0: must change now, NULL: never) |
 | `meta.v(name)` | text | The session-state value of an item (use it inside functions and `DO` blocks) |
 | `meta.set_tenant(tenant)` | void | Sets (or with NULL or `''` clears) the current session's tenant (APEX: `apex_session.set_tenant_id`): at once and for the session's next requests. Workflows and tasks then carry it and show only to that tenant ([chapter 6](06-processing.md#tenants)) |
@@ -93,6 +98,22 @@ select meta.web_request_source('EXCHANGE', '{"currency": "EUR"}');
 - Application roles can't read `meta.web_request_log`; the owner can, e.g. in the SQL Workshop:
   `select id, status, status_code, url, message from meta.web_request_log order by id desc`.
 
+### E-mail from SQL
+
+[Sending e-mail](06-processing.md#sending-e-mail) (APEX: `APEX_MAIL`). The application needs a mail
+service (an administrator chooses it under Workspace utilities → Mail services).
+
+| Function | Returns |
+|---|---|
+| `meta.send_mail(p_to, p_subject, p_body, p_body_html, p_from, p_cc, p_bcc, p_reply_to)` | Queues a mail and returns its id (APEX_MAIL.SEND). `p_to`, `p_cc`, `p_bcc`: addresses separated by commas or semicolons, at most 50 together (plain addresses, no display names); `p_subject`: one line, at most 998 characters; `p_body` (plain text) and/or `p_body_html`, each at most 1 MB; `p_from`: an address the service may send as (default: the application's); `p_reply_to`: one address |
+| `meta.send_mail_template(p_template, p_placeholders jsonb, p_to, p_cc, p_bcc, p_from, p_reply_to)` | The same with an [e-mail template](06-processing.md#e-mail-templates) and its placeholder values (APEX_MAIL.SEND with `p_template_static_id`) |
+| `meta.add_mail_attachment(p_mail_id, p_content bytea, p_filename, p_mime)` | Adds a file to a mail queued **in the same transaction** (APEX_MAIL.ADD_ATTACHMENT); at most 20 files and 20 MB per mail, 10 MB per file |
+| `meta.mail_status(p_mail_id)` | `queued`, `sending`, `sent`, `error` or `cancelled`; NULL for another application's mail |
+
+The mail is sent by the server **after the transaction commits**. Over the application's limit per
+day `meta.send_mail` raises an error. Application roles can't read the queue; the owner can:
+`select id, app_id, to_addresses, subject, status, attempts, message from meta.mail_queue order by id desc`.
+
 ### Push notifications from SQL
 
 APEX_PWA push notifications ([chapter 17](17-mobile.md#push-notifications)); the application needs

package/docs/guide/11-from-apex.md

@@ -47,12 +47,17 @@ What's missing is listed in the [feature parity matrix](../apex-feature-parity.m
 | Rich Text Editor, Markdown Editor, Star Rating, Combobox, QR Code | Item types `richtext` (sanitised HTML), `markdown`, `rating`, `combobox` (colon-separated), `qrcode`; plus `daterange` (`from:to`) and `{"reveal": true}` on password items ([chapter 5](05-items.md)) |
 | Data Generator (sample data for development, 26.1) | SQL Workshop → **Sample Data**: generators proposed per column, foreign keys to existing parent rows, a seed, preview, insert in one transaction (parents first), SQL/CSV download, saved definitions ([chapter 16](16-files.md#sql-workshop--sample-data)) |
 | Data Workshop (load and unload: CSV, Excel, JSON, XML) / Data Load Definition, *Execute Data Load* process | SQL Workshop → Load Data and **Unload Data** (CSV, JSON, Excel, XML; [chapter 16](16-files.md#sql-workshop--unload-data)); Shared Components → Data load definitions; process type `data_load` with `"definition"` ([chapter 16](16-files.md#data-loading)) |
+| SQL Workshop → Utilities → Generate DDL, Schema Comparison | SQL Workshop → **DDL** and **Compare**: a schema's DDL in an order that runs; two schemas compared by their DDL with a change script; also `pgkiln ddl` and `pgkiln compare` ([chapter 3](03-builder.md#sql-workshop)) |
 | SQL Workshop → SQL Scripts, Quick SQL, Query Builder | The same names in the SQL Workshop: saved scripts with a result per statement and a run history, shorthand → PostgreSQL DDL, a SELECT built on a canvas of tables, joined by foreign keys or columns you connect, with column functions and grouping ([chapter 3](03-builder.md#sql-workshop)) |
 | Interactive report *Download → PDF*, printing | Actions → Download PDF, Print ([chapter 16](16-files.md#printing)) |
 | Pagination *Row Ranges X to Y*, *Maximum Row Count*, region *Lazy Loading*, *Server Cache* | `"pagination": "range"`, `max_rows`, `"lazy": true`, `"cache": {"scope", "seconds"}` ([large tables](04-pages-and-regions.md#large-tables)) |
 | `APEX_UTIL.CHANGE_CURRENT_USER_PW`, `RESET_PASSWORD`, `EXPIRE_END_USER_ACCOUNT` | My account page; `meta.set_password()`, `meta.expire_password()` ([chapter 8](08-security.md#passwords-and-my-account)) |
 | Progressive Web App push notifications: `APEX_PWA.SEND_PUSH_NOTIFICATION`, `HAS_PUSH_SUBSCRIPTION`, *Send Push Notification* process, the subscription settings page | `meta.send_push(user, title, body, page, items)`, `meta.has_push_subscription(user)`, process type `send_push`, *My account → Notifications* and the dynamic action `push_subscribe` ([chapter 17](17-mobile.md#push-notifications)) |
-| `APEX_MAIL`, Send E-Mail process, e-mail templates | Not included: pgkiln doesn't send mail. Queue mail in a table and deliver it with your own service, or use an extension such as `pg_smtp_client` ([chapter 15](15-extensions.md)) |
+| `APEX_MAIL`, Send E-Mail process, e-mail templates | `meta.send_mail`, `meta.send_mail_template`, `meta.add_mail_attachment`, the `send_email` process and Shared Components → E-mail templates (`#NAME#` placeholders) ([chapter 6](06-processing.md#sending-e-mail)). Instead of the instance's SMTP settings: mail services with SMTP (password or OAuth2), Microsoft Graph, Amazon SES, Resend, Postmark, SendGrid or Mailgun. `APEX_MAIL.PUSH_QUEUE` is not needed: mail goes out right after the commit |
+| `APEX_APP_SETTING`, `APEX_UTIL.GET/SET/REMOVE_PREFERENCE`, *Maintain session state: Per User* | Shared Components → Application settings and `meta.get_app_setting`/`meta.set_app_setting`; `meta.get_preference`/`set_preference`/`remove_preference`; `{"persist": "user"}` on an item ([chapter 6](06-processing.md#application-settings)) |
+| `APEX_DATA_EXPORT.EXPORT` | `meta.data_export(query, format, options)` (CSV, JSON, XML, HTML) and the download process's `{"export": "xlsx"}` (also PDF) ([chapter 6](06-processing.md#data-export-from-sql)) |
+| `APEX_LANG.LANG`, dynamic translations | Shared Components → Dynamic translations and `meta.lang(text)` ([chapter 14](14-globalization.md#dynamic-translations)) |
+| Display Image, Geocoded Address items | Item types `image` and `address` (geocoder: `GEOCODER_URL`) ([chapter 5](05-items.md#display-image-and-geocoded-address)) |
 | Translated applications (XLIFF), `APEX_LANG.MESSAGE`, `&APP_TEXT$NAME.` | Translations in the app (XLIFF/CSV import and export), `meta.message()`, `&APP_TEXT$NAME.` ([chapter 14](14-globalization.md)) |
 | Application date format mask | Settings → Globalization → Date format (Oracle-style masks) |
 | Number format masks (`FML999G999G990D00`) on columns and items | `{"formats": {...}}` on report, grid and cards columns, `{"format_mask": "..."}` on charts and number/display items ([chapter 14](14-globalization.md#number-formats)) |
@@ -93,7 +98,9 @@ in to a second app is then silent via the identity provider's session. See
 Active Directory** passwords work the same way (groups → roles), and *Keep me signed in* matches
 APEX's persistent authentication. **Database accounts** sign in with PostgreSQL login roles, and
 **custom authentication** calls your own PL/pgSQL function (APEX: a custom PL/SQL scheme), see
-[chapter 8](08-security.md#custom-authentication-a-plpgsql-function).
+[chapter 8](08-security.md#custom-authentication-a-plpgsql-function). The **login page** (APEX: page 9999 with
+the Login region template) is a page you design in the Page Designer around a **Login** region, and
+**Forgot password?** is built in (APEX apps build their own), see [chapter 8](08-security.md#the-login-page).
 
 ## ORDS and PostgREST
 

package/docs/guide/12-development.md

@@ -34,6 +34,8 @@ src/
   app.ts / server.ts       Fastify setup / entry point
   db.ts                    the two pools, appTx() (SET LOCAL ROLE + pgkiln.* settings, NOTICEs to the debug log), savepoints
   security.ts              URL checksums, password policy, security headers (CSP nonce), throttling limits
+  ddl.ts                   Generate DDL and Schema Comparison: readSchema (catalog → one DDL per object, unqualified), ddlScript (order), compare, changeScript
+  static-version.ts        the version of app.css, app.js, icons.svg and sw.js (?v= in their URLs, the service worker version): content hash, looked at again when a file changes
   session.ts               sessions (hashed tokens), activity log, login throttling
   sso.ts                   OpenID Connect: discovery, sign-in flow, ID token checks, account linking
   saml.ts                  SAML 2.0 sign-in (node-saml): AuthnRequest, response checks, SP metadata
@@ -68,6 +70,7 @@ src/
   css.ts                   PageCss: data-dependent styles as classes in the page's nonce'd <style> (CSP)
   metadata.ts              types + loaders for apps and pages (components of excluded build options are left out here)
   maptiles.ts              map tile server URL, attribution and CSP origin
+  geocode.ts               the installation's geocoder for address items (GEOCODER_URL, Nominatim search API)
   mvt.ts                   Mapbox Vector Tile encoding for map layers served as tiles
   yamltext.ts              the text style of the directory export: a strict YAML subset, written and read
   webclient.ts             outgoing HTTP to web services: allow-list, address checks at connect time (SSRF), redirects, limits
@@ -80,6 +83,11 @@ src/
   webrequests.ts           web requests from SQL (meta.web_request, migration 052): runPending() after each sql page process
                            (same transaction), webRequestTick() for committed ones (automations scheduler), retention purge;
                            calls go through websources.ts call()/invoke() (allow-list, SSRF checks, credentials)
+  mail/                    e-mail (migration 081): providers.ts (one deliver() per provider: SMTP through nodemailer with a password
+                           or XOAUTH2, Microsoft Graph sendMail, Amazon SES v2 raw MIME with signV4, Resend, Postmark, SendGrid,
+                           Mailgun, log; MailError says whether a retry may help; client-credentials token cache; settingsProblems),
+                           mail.ts (sendWith(): service enabled, allowed sender, secret decrypted; mailTick(): claim with SKIP LOCKED,
+                           send, retry after 1/4/16/64 minutes, purge after 30 days; the NOTIFY pgkiln_mail listener)
   ai/                      AI services (migration 060): types.ts (the provider interface, AiError kinds),
                            anthropic.ts (Claude through @anthropic-ai/sdk: streamed, effort, structured outputs via
                            output_config.format, refusal fallbacks, stop_reason checks, typed SDK errors), openai.ts (the openai
@@ -93,6 +101,8 @@ src/
   icons.ts                 icon helper (sprite in public/icons.svg)
   runtime/
     routes.ts              HTTP handlers: show, submit, dynamic actions, cascading lists, login
+    signin.ts              the sign-in form (built-in page and the login region of an application's own login page), safeNext, passwordResetAvailable
+    password-reset.ts      Forgot password: request (same answer either way), the link (token into the session), the new password
     context.ts             PageContext, dbg()/timed() debug helpers, bind values, substitutions, public error messages, writeOut (streamed responses with back pressure)
     authz.ts               authorization schemes, conditions, visibility (menu requests count as buttons)
     engine.ts              form fetch, validations, processes (conditions, execution chains, queueing background chains; web requests queued by an sql process are made right after it), application processes
@@ -103,7 +113,7 @@ src/
                            style (user choice, default), themeCss() (only hex values and constants reach the CSS)
     template-options.ts    template options: the fixed CSS class list per region and button, templateClasses() (unknown values ignored)
     regions.ts             region shell + chart (drill-down links, gauge settings)/cards/dynamic dispatch with row limits, lazy placeholder and cache, buttons (menu buttons, badges)
-    report.ts, report-views.ts (group by, pivot, chart), compute.ts (computed column expressions), grid.ts (aggregates, row actions, Actions menu, layoutFromForm), grid-layout.ts (column layouts: clean, arrange, per user), master-detail.ts (signed master row selection, details), facets.ts, items.ts
+    report.ts, report-views.ts (group by, pivot, chart), compute.ts (computed column expressions), grid.ts (aggregates, row actions, Actions menu, single row view, layoutFromForm), grid-layout.ts (column layouts: clean, arrange, per user), master-detail.ts (signed master row selection, details), facets.ts, items.ts
                            (report.ts: paging with row ranges and max_rows, keyset paging (keysetPlan, seekCondition, signed r<id>_k), pagerNav, streamed CSV/Excel downloads with a cursor;
                            items.ts: lovOptions, searchLov/lovLookup for popup LOVs, served by POST /a/:alias/:page/lov/:item/search in routes.ts)
     region-cache.ts        region caching (keys per scope, CSRF placeholder, invalidation on submit) and lazy regions (GET …/region/:id is in routes.ts)
@@ -142,6 +152,21 @@ src/
                            session, formatAnswer (escaped), send/clear routes
     ai-filter.ts           natural-language filters on a report ("ai_filter"): columns → structured output → checked → r<id>_f/q/s/d
     pdf.ts                 report PDFs with report layouts (pdfkit); rows from a cursor in batches (tablePdf takes batches)
+    search.ts              search region and search configurations (migration 080): words as ILIKE parameters, table/sql/list
+                           sources as the app role in savepoints, marked results, configColumns/searchConfigProblems for the Advisor
+    url-region.ts          URL region (migration 078): literal origins only (urlTarget), &ITEM. URL-encoded, sandbox and height,
+                           frameOrigins() for the CSP's frame-src (security.ts)
+    ajax.ts                Ajax callbacks (migration 085: POST …/ajax/:name, point "ajax" processes, x01 … x10 binds) and the
+                           download dynamic action (POST …/da/:id/download)
+    availability.ts        availabilityRefusal(): who may use an application (migration 083); loadContext, the login page
+                           and REST modules ask it (PostgREST: meta.api_check)
+    feedback.ts            users' feedback page and the navigation bar entry (migration 084)
+    data-items.ts          display image and address items (migration 086): imageUrl (https origins into the CSP's img-src),
+                           GET …/image/:item (a BLOB from the item's query), POST …/geocode/:item, and items kept per user
+                           (loadPreferences / savePreferences through meta.get_preference / set_preference)
+    data-export.ts         the download process's {"export": …}: meta.data_export for csv/json/xml/html, Excel and PDF here
+    devbar.ts              developer toolbar and session state viewer (migration 079): the pgkiln_devbar token of a builder
+                           session (ensureDevbar/devbarOf), the toolbar markup, the viewer, clear and per-session debug routes
   builder/
     components.ts          property spec of every component (drives the property editor)
     ui.ts                  IDE shell (icon rail, toolbar, breadcrumb, status bar), builder theme, form helpers, CSRF check, app tabs
@@ -158,6 +183,14 @@ src/
     appwizard.ts           Create → From pasted data (kept as a temp file, then the From a file steps) and From existing tables
                            (a schema's tables/views → report+form or report pages, navigation, dashboard)
     forms.ts               generic component property form (lookups, render, save)
+    backups.ts             Application → Backups (migration 082): list, back up now, download, restore (replaceApp), keep N;
+                           backupTick() for the scheduler's daily backups of changed applications
+    availability.ts        Application → Availability (migration 083): status, message, users, build status (Run only is
+                           enforced by locks.ts blockingLock); availabilityBadge() in the application header
+    feedback.ts            Application → Feedback (migration 084): the setting, the list with filters, status and answers
+    region-help.ts         the Attributes (JSON) help per region type, with links to the guide
+    mail.ts                Workspace utilities → Mail services (administrators: providers, write-only secret, allowed senders,
+                           applications with From and daily limit, test) and Applications → Activity → Mail (retry, cancel)
     shared.ts              Shared Components and access control
     designer.ts            page designer: component tree (with computations and branches), layout canvas and gallery, property editor, toolbar
     arrange.ts             page designer layout changes: move, column span, create from the gallery, undo / redo
@@ -177,6 +210,8 @@ src/
     region-settings.ts     page designer: settings forms for grid, chart (gauge, drill-down), cards, calendar (views, create, drag and drop), facets, smart filters, display selector, list
     search.ts              app search, "where used" (appEntries, search, whereUsed, usedInPanel)
     advisor.ts             Advisor: EXPLAIN every SQL fragment, reference checks, plpgsql_check
+    ddl-tools.ts           SQL Workshop → DDL and Compare (src/ddl.ts)
+    login-page.ts          Application settings → Login page and Forgot password; Create a login page (page 9999)
     top-sql.ts             Top SQL per app role from pg_stat_statements
     diagnostics.ts         Activity → Debug messages (level, list, one request's entries, purge); Workspace utilities →
                            Installation (version, install/upgrade runs, applied and missing migrations; administrators)
@@ -377,5 +412,8 @@ browser enhancements at the end of `public/app.js` (the item must work without t
 1. Update `CHANGELOG.md` and the version in `package.json`.
 2. Merge to `main`; CI must be green (every job). The `main` branch should be protected on
    GitHub (Settings → Branches → rule for `main`: require the CI checks).
-3. Tag: `git tag -a vX.Y.Z -m vX.Y.Z && git push origin vX.Y.Z`.
+3. Tag: `git tag -a vX.Y.Z -m vX.Y.Z && git push origin vX.Y.Z`. The tag publishes the Docker image
+   (`docker-publish.yml`: `pgkiln/pgkiln` and `ghcr.io/pgkiln/pgkiln`, amd64 and arm64) and the npm package
+   (`npm-publish.yml`, trusted publishing with provenance; it refuses a tag that doesn't match
+   `package.json`). Then `gh release create vX.Y.Z` with the changelog section as notes.
 4. Add the new tag to the `upgrade` job's matrix in `.github/workflows/ci.yml` (see above).

package/docs/guide/14-globalization.md

@@ -98,6 +98,21 @@ raise exception '%', meta.message('LEAVE_OVERLAP', to_char(p_start, 'DD-MM-YYYY'
 
 The HR sample's dashboard uses them for its key figures (`examples/hr/hr_04_i18n.sql`).
 
+### Dynamic translations
+
+For **values from tables** (department names, statuses, list of values entries), use dynamic
+translations (APEX: *Dynamic Translations*, `APEX_LANG.LANG`): **Shared Components → Dynamic
+translations** holds a language, the text as stored and its translation, and `meta.lang` returns
+the text in the session's language:
+
+```sql
+select meta.lang(dname) as d, deptno as r from hr.dept order by 1   -- a list of values
+```
+
+An exact language match wins, then the base language (`nl-BE` → `nl`), else the text as it is.
+`meta.lang(text, 'de')` asks for another language. Dynamic translations are exported with the
+application (`globalization/dynamic-translations.yaml` in an application's files).
+
 ### Date formats
 
 Dates and timestamps in reports, grids and display items are formatted with a **mask**:

package/docs/guide/15-extensions.md

@@ -109,7 +109,7 @@ Audit triggers record such changes as made by `nobody`, which is what you want f
 | **[pgmq](https://github.com/pgmq/pgmq)** | A message queue in Postgres for background work handled by a worker service | Like AWS SQS, transactional |
 | **pg_partman** | Partition big append-only tables such as `meta.activity_log` by month | Only needed at high volume |
 | **[plv8](https://github.com/plv8/plv8)** | Server-side JavaScript functions | Like APEX's MLE JavaScript. Maintained upstream, but some hosts (e.g. Supabase on PostgreSQL 17) no longer offer it, so check before depending on it |
-| **[pg_smtp_client](https://github.com/brianpursley/pg_smtp_client)** | Sending e-mail from SQL, if your team needs it | pgkiln deliberately doesn't send mail ([chapter 11](11-from-apex.md)). This keeps mail out of pgkiln and in your own schema |
+| **[pg_smtp_client](https://github.com/brianpursley/pg_smtp_client)** | Sending e-mail synchronously from SQL, outside an application | pgkiln itself sends mail queued with `meta.send_mail` after the commit, through SMTP, Microsoft Graph, Amazon SES or an HTTP API ([chapter 6](06-processing.md#sending-e-mail)); this extension talks SMTP from the database itself |
 
 ## Security notes
 

package/docs/guide/17-mobile.md

@@ -27,7 +27,9 @@ Everything is per application, under its own address: `/a/<alias>/manifest.webma
 ## Offline
 
 - **The app shell** (pgkiln's CSS, script and icons) and an offline page are stored when the app is
-  installed, so the app always opens.
+  installed, so the app always opens. Pages ask for these files with a version in the URL
+  (`/static/app.css?v=…`, from the files' contents); when pgkiln is upgraded, or a file changes,
+  devices fetch the new one at the next page load.
 - **Pages** are fetched from the network first. Without a connection, a page the user opened before
   comes from the device (when *Keep visited pages* is on); otherwise the offline page appears,
   listing the pages that are on the device.

package/docs/guide/18-cli.md

@@ -35,8 +35,10 @@ any (see [what is not exported](03-builder.md#export-format)).
 | `pgkiln migrate [--example <name>]` | Applies the migrations that were not applied yet, then optionally `examples/<name>/` (same as `npm run db:migrate` / `npm run example:hr`; `--root` and `--seed` as in `scripts/migrate.ts`) |
 | `pgkiln apps [--json]` | Lists the applications: alias, number of pages, name |
 | `pgkiln export <alias> [--format json\|dir\|text] [--out <path>]` | `json` (default): the `pgkiln/2` document with sorted keys, to `--out` or standard output. `dir`: a directory (default `./<alias>`), see below. `text`: the same directory in YAML with the code inline ([text files](#text-files-apexlang)) |
-| `pgkiln import <path> [--alias <alias>] [--replace]` | Imports a JSON export, an application directory or a `.zip` of one. `--alias` gives the copy another alias. `--replace` updates the application with that alias in place |
+| `pgkiln import <path> [--alias <alias>] [--replace] [--check [--force] \| --dry-run]` | Imports a JSON export, an application directory or a `.zip` of one. `--alias` gives the copy another alias. `--replace` updates the application with that alias in place (after a [backup](03-builder.md#backups)). `--check` checks the application before it commits, `--dry-run` only checks ([below](#checking-before-an-import)) |
 | `pgkiln diff <alias> <path> [--name-only \| --quiet]` | What differs between the application in the database and a directory (or JSON file, or zip) |
+| `pgkiln ddl <schema> [--no-comments] [--no-grants] [--out <file>]` | The DDL of a schema's objects, in an order that runs (as SQL Workshop → DDL, [chapter 3](03-builder.md#sql-workshop)) |
+| `pgkiln compare <source> <target> [--script]` | Compares two schemas: `+` only in the source, `-` only in the target, `~` different; exit code 1 when they differ. `--script` writes the script that makes the target like the source (drops commented out); nothing is run |
 | `pgkiln mcp` | An MCP server on standard input/output for AI coding agents, see [chapter 20](20-ai-agents.md) |
 | `pgkiln plugin build <dir> [-o <file>]` | Builds a plug-in file (`pgkiln-plugin/2`) from a source directory, see [plug-ins](04-pages-and-regions.md#plug-ins-with-their-own-code) |
 | `pgkiln plugin install <file\|dir> --app <alias> [--replace]` | Adds a plug-in (file or source directory) to an application; its install SQL is not run |
@@ -187,6 +189,9 @@ the files any more are removed. What belongs to this installation stays:
   [chapter 19](19-rest-data-sources.md#web-credentials)).
 - the **style variant each user chose** ([chapter 14](14-globalization.md#style-variants-theme-roller));
   a style that the file no longer has falls back to the default.
+- its **availability and build status** ([chapter 3](03-builder.md#availability-and-build-status)): exports
+  leave them out, so a deployment doesn't open an application you closed, or close one;
+- its **backups**: the version the import replaces is the newest one ([chapter 3](03-builder.md#backups)).
 
 It all happens in one transaction; any error leaves the application unchanged. Without an
 application with that alias, `--replace` simply imports, so the same command deploys the first
@@ -201,6 +206,32 @@ pgkiln diff hr apps/hr                           # on the target: what would cha
 pgkiln import apps/hr --replace                  # deploy
 ```
 
+### Checking before an import
+
+An import doesn't need the application's tables, columns and functions to exist (neither does APEX's):
+a page whose SQL names a missing table imports fine and fails when it runs. `--check` asks the
+[Advisor](03-builder.md#advisor) first, inside the import's transaction, before anything is committed:
+every SQL fragment is planned as the application's database role (unknown tables, columns,
+functions and types, missing grants), PL/pgSQL blocks are compiled, and references to pages,
+items, lists of values, schemes and search configurations are checked.
+
+```sh
+pgkiln import apps/hr --replace --check      # errors: nothing changes, exit code 1
+pgkiln import apps/hr --replace --dry-run    # only check (exit code 0 without errors)
+pgkiln import apps/hr --replace --check --force   # report, import anyway
+```
+
+```text
+ERROR  page 2, region Employees (Source): relation "hr.employee" does not exist
+WARNING  page 3, item P3_SAL (Default value): …
+Check: 1 error(s), 1 warning(s), 0 note(s).
+Not imported: the check found 1 error(s). Fix them, or use --force.
+```
+
+Deploy the database changes (your migration scripts) before the application, so the check sees
+the tables the new version needs. The MCP server's `import_app` checks by default; the builder's
+Import page has the check ticked.
+
 `export --format dir` into an existing directory removes the files of deleted components and
 leaves dot files (`.git`, `.gitattributes`) alone; it refuses a non-empty directory without a
 `pgkiln.json`, so a typo can't empty the wrong folder.

package/docs/guide/20-ai-agents.md

@@ -48,12 +48,14 @@ directory the agent started the server in (the project).
 | `get_page` | every component of one page as YAML, SQL inline | no |
 | `read_app_files` | component files by path or prefix (`shared/lovs/`, `navigation.yaml`, …) | no |
 | `describe_schema` | schemas with tables, views and functions; or one table with columns, constraints, indexes, RLS policies and triggers | no |
+| `generate_ddl` | the DDL of a schema's objects, in an order that runs: a start for a migration script | no |
+| `compare_schemas` | the differences between two schemas and a script that makes the target like the source (not run) | no |
 | `run_query` | one SQL statement, read-only, rows as JSON | no |
 | `search_docs` | searches this user guide, the parity matrix and SECURITY.md | no |
 | `recent_errors` | the latest errors and refused requests from the activity log | no |
 | `export_app` | writes an application to a directory (default `apps/<alias>`, format `text`) | files on disk |
 | `diff_app` | what an import of a directory would change (A/D/M with unified diffs); also reports files it can't read | no |
-| `import_app` | imports a directory, zip or JSON file; `replace: true` updates the application in place | the database |
+| `import_app` | imports a directory, zip or JSON file; `replace: true` updates the application in place. It checks the application first (the Advisor, in the import's transaction): errors refuse the import and are listed; `force: true` imports anyway, `dry_run: true` only checks | the database |
 
 The files are the [directory format](18-cli.md#the-directory-format) of the command line, in the
 [text style](18-cli.md#text-files-apexlang): one YAML file per component, with SQL, PL/pgSQL and
@@ -67,7 +69,8 @@ users, sessions and saved reports kept, supporting objects and plug-in install S
    `describe_schema` for the tables; `search_docs` before guessing a property or region type.
 2. `export_app` to `apps/<alias>`, then edit the YAML files there.
 3. `diff_app`, so you (and it) see exactly what will change.
-4. `import_app` with `replace: true`. Open the page in the browser to check.
+4. `import_app` with `replace: true`. When it names errors (a missing column, a typo in SQL), the agent fixes
+   the files and imports again; nothing was changed. Open the page in the browser to check.
 
 Tables, views and functions are ordinary PostgreSQL objects: an agent changes them in your
 migration scripts, not in the application files (`run_query` can't change them anyway).

package/examples/hr/hr_50_search.sql

@@ -0,0 +1,47 @@
+-- =====================================================================
+-- HR example, part 50: search configurations and the search region
+-- (migration 080; docs/guide/04-pages-and-regions.md, search region)
+--
+-- Page 42 "Search": one field searches three sources as you type:
+--   - EMPLOYEES: a query (employees with their department), each result
+--     opens the employee's form (page 3);
+--   - DEPARTMENTS: the table hr.dept, each result opens page 5;
+--   - SHORTCUTS: the entries of the list HR_SHORTCUTS the user may see.
+-- =====================================================================
+
+insert into meta.search_config (app_id, name, label, seq, source_type, source, searchable_columns,
+                                title_column, subtitle_column, badge_column, icon, link)
+select a.id, c.name, c.label, c.seq, c.source_type, c.source, c.searchable, c.title, c.subtitle, c.badge, c.icon, c.link::jsonb
+  from meta.app a, (values
+  ('EMPLOYEES', 'Employees', 10, 'sql',
+   $q$select e.empno, initcap(e.ename) as name, initcap(e.job) as job, initcap(d.dname) as department
+  from hr.emp e left join hr.dept d on d.deptno = e.deptno$q$,
+   '{name,job,department}'::text[], 'name', 'job', 'department', 'user', '{"page": 3, "items": {"P3_EMPNO": "#EMPNO#"}}'),
+  ('DEPARTMENTS', 'Departments', 20, 'table', 'hr.dept', '{dname,loc}'::text[], 'dname', 'loc', null, 'building',
+   '{"page": 5, "items": {"P5_DEPTNO": "#DEPTNO#"}}'),
+  ('SHORTCUTS', 'Shortcuts', 30, 'list', 'HR_SHORTCUTS', '{}'::text[], null, null, null, 'link', null)
+  ) as c (name, label, seq, source_type, source, searchable, title, subtitle, badge, icon, link)
+ where a.alias = 'hr';
+
+insert into meta.page (app_id, page_no, name, title, parent_page)
+select id, 42, 'Search', 'Search', 1 from meta.app where alias = 'hr';
+
+insert into meta.region (page_id, seq, title, type, columns, template, config)
+select p.id, 10, 'Search', 'search', 12, 'standard',
+       '{"configs": ["EMPLOYEES", "DEPARTMENTS", "SHORTCUTS"], "placeholder": "Search employees, departments and shortcuts…"}'
+  from meta.page p join meta.app a on a.id = p.app_id where a.alias = 'hr' and p.page_no = 42;
+
+insert into meta.nav_entry (app_id, seq, label, icon, target_page)
+select id, 2, 'Search', 'search', 42 from meta.app where alias = 'hr';
+
+insert into meta.translation (app_id, language, source, target)
+select a.id, 'nl', t.source, t.target
+  from meta.app a, (values
+  ('Search', 'Zoeken'),
+  ('Employees', 'Medewerkers'),
+  ('Departments', 'Afdelingen'),
+  ('Shortcuts', 'Snelkoppelingen'),
+  ('Search employees, departments and shortcuts…', 'Zoek medewerkers, afdelingen en snelkoppelingen…')
+  ) as t (source, target)
+ where a.alias = 'hr'
+on conflict do nothing;

package/examples/hr/hr_51_mail.sql

@@ -0,0 +1,70 @@
+-- =====================================================================
+-- HR example, part 51: e-mail (migration 081; docs/guide/06-processing.md,
+-- "Sending e-mail")
+--
+-- The example sends through a mail service of provider "log": the server
+-- writes each mail to its log and sends nothing, so the example works on
+-- any installation. An administrator points HR at a real service under
+-- Workspace utilities → Mail services (SMTP, Microsoft 365, Amazon SES,
+-- Resend, Postmark, SendGrid or Mailgun).
+--
+-- The template LEAVE_DECIDED tells an employee that a leave request was
+-- approved or rejected; a trigger queues it from the running application
+-- when the status changes (the decision's transaction: a rollback sends
+-- nothing). A mail that can't be queued never stops the decision.
+-- =====================================================================
+
+insert into meta.mail_service (name, description, provider, senders, settings)
+values ('DEVELOPMENT_LOG', 'Writes mail to the server log; sends nothing', 'log', '{@example.com}', '{"default_from": "hr@example.com"}')
+on conflict (name) do nothing;
+
+insert into meta.app_mail_service (app_id, service_id, from_address, max_per_day)
+select a.id, s.id, 'hr@example.com', 500
+  from meta.app a, meta.mail_service s
+ where a.alias = 'hr' and s.name = 'DEVELOPMENT_LOG'
+on conflict (app_id) do nothing;
+
+insert into meta.email_template (app_id, name, subject, html_body, text_body)
+select id, 'LEAVE_DECIDED', 'Your leave request was #STATUS#',
+$h$<p>Dear #NAME#,</p>
+<p>Your leave request from <b>#START#</b> to <b>#END#</b> was <b>#STATUS#</b> by #DECIDED_BY#.</p>
+<p>Kind regards,<br>HR</p>$h$,
+$t$Dear #NAME#,
+
+Your leave request from #START# to #END# was #STATUS# by #DECIDED_BY#.
+
+Kind regards,
+HR$t$
+  from meta.app where alias = 'hr';
+
+create function hr.mail_leave_decided() returns trigger
+language plpgsql security definer set search_path = hr, pg_catalog as $$
+declare
+  v_email text;
+  v_name  text;
+begin
+  if new.status not in ('APPROVED', 'REJECTED') or meta.app_id() is null then
+    return new;
+  end if;
+  select a.email, initcap(e.ename) into v_email, v_name
+    from hr.emp e join meta.account a on lower(a.username) = lower(e.username)
+   where e.empno = new.empno;
+  if v_email is null then
+    return new;
+  end if;
+  perform meta.send_mail_template('LEAVE_DECIDED', jsonb_build_object(
+    'NAME', v_name,
+    'STATUS', lower(new.status),
+    'START', to_char(new.start_date, 'DD Mon YYYY'),
+    'END', to_char(new.end_date, 'DD Mon YYYY'),
+    'DECIDED_BY', coalesce(new.decided_by, 'HR')), v_email);
+  return new;
+exception when others then
+  raise warning 'hr.mail_leave_decided: %', sqlerrm;
+  return new;
+end
+$$;
+
+create trigger leave_decided_mail after update of status on hr.leave_request
+  for each row when (old.status is distinct from new.status)
+  execute function hr.mail_leave_decided();

package/examples/hr/hr_52_feedback.sql

@@ -0,0 +1,15 @@
+-- =====================================================================
+-- HR example, part 52: feedback (migration 084; docs/guide/03-builder.md,
+-- "Feedback")
+--
+-- Users send feedback about a page from the navigation bar's Feedback link;
+-- developers answer under Application → Activity → Feedback. One answered
+-- example from the user king.
+-- =====================================================================
+
+update meta.app set feedback = true where alias = 'hr';
+
+insert into meta.feedback (app_id, page_no, username, kind, rating, body, status, response, responded_by, responded_at)
+select id, 2, 'king', 'idea', 4, 'Could the employee list show the hire date as well?', 'done',
+       'Added in the column list: open Actions → Columns and show "Hiredate".', 'admin', now()
+  from meta.app where alias = 'hr';