pgkiln 0.54.0 → 0.56.0

package/SECURITY.md

@@ -109,6 +109,8 @@ first version (MVP). Every finding below has a regression test in
 | Mail queue, workspace mail and network access (sprint 118) | Administration → Mail queue: administrators see every workspace, a workspace's administrators only their current workspace's applications, other developers get 403; Retry and Purge (one mail or all failed) check the mail's workspace again on the server and need the CSRF token; bodies and attachments are never shown. A workspace's own mail service is managed by its administrators only; its secret is encrypted like a web credential's, write-only, never shown or exported (not in the workspace export); it has no API base URL or token URL, and its SMTP host must pass the installation's allow-list and the workspace's network access list and resolve to a public address (unless `PGKILN_REST_PRIVATE_HOSTS` lists it), resolved once and connected to by that address (no DNS rebinding). A workspace's network access list narrows `PGKILN_REST_ALLOWED_HOSTS` on the server for every outgoing web call of its applications (`meta.web_request`, REST data sources incl. write-back and the response cache, invoke API, token endpoints, object storage, the builder's Test, REST source catalogs), on every redirect hop; it can't widen the installation's list or the private-address checks. Refusals go to the debug log and `meta.network_refusal` (7 days). Also fixed: *REST source catalogs → read from a URL* fetched the URL before checking the developer's session (any visitor could make the server call an allowed host); it is now read only after the developer and CSRF checks. |
 | Data security per table (sprint 119) | SQL Workshop → a table → Security writes `GRANT` / `REVOKE` and a masking view, so it needs a signed-in developer and the CSRF token, and works only on tables of the workspace's schemas (never pgkiln's own or the system's: 404). Table, column, view and role names reach SQL quoted; view names and application roles that could break out of their quotes are refused. The masking role is `nologin`, a member of the reader roles, so row level security still applies inside the view, and the generated SQL refuses to run when that role would bypass RLS. MCP `run_query` with an application runs as that application's database role (read-only) and refuses unknown applications. |
 | App Gallery (sprint 120) | Installing a sample app runs shipped SQL as the owner, so only administrators may, with the CSRF token, into their current workspace; a request names only a key of `gallery.json` of its own kind (sample, starter, utility), never a path, and the file names in the catalogue must match fixed patterns. The script and the workspace placement run in one transaction: a failing script leaves nothing behind. Utility apps are blueprints: any developer installs one into their own workspace, only after the review. An installed sample is edited only from its own workspace. The search term is escaped. |
+| Builder language (sprint 121) | Only the codes of the builder's languages are accepted: anything else on a sign-in link is ignored (also a repeated parameter), the status bar's menu refuses it (400) and checks the CSRF token. A sign-in link sets only an HttpOnly, SameSite=Lax cookie that the sign-in page reads; a developer's stored choice changes only through their own signed-in session. Translated texts are escaped like the English ones; placeholders are filled with escaped values unless the code passes markup on purpose (`tx.rich`). |
+| Ask and smart filters set facets (sprint 122) | A phrase can only set facets of the faceted search and smart filters regions on the page that the user sees, on their configured columns; values and range bounds become the facets' own URL parameters (bounds checked as numbers or dates) and reach SQL as query parameters, never as text. Values in a phrase are looked up in the report's rows with a query parameter, as the application's role. A facet chip's Remove is checked against the chips the form showed (a tampered key is refused). Sample apps keep their demo accounts with known passwords: install them on development or demo instances only. |
 
 ## Findings of the MVP review and their fixes
 

package/db/migrations/127_builder_language.sql

@@ -0,0 +1,16 @@
+-- ---------------------------------------------------------------------
+-- 127: the builder in more languages (sprint 121, WS-7; APEX: the
+-- builder's language links on the sign-in page and the workspace home).
+--
+-- meta.developer.language: the builder language each developer chose (the
+-- language menu in the builder's status bar, or a language link on the
+-- builder's sign-in page); null = English. The builder's own texts are
+-- message files in src/builder/i18n/ (en, de, es, fr, nl, pt); the check
+-- keeps the column to codes of that shape, the server accepts only the
+-- languages it has. A developer account is installation data: not
+-- exported with an application or a workspace.
+-- ---------------------------------------------------------------------
+alter table meta.developer
+  add column language text check (language ~ '^[a-z]{2}(-[A-Z]{2})?$');
+comment on column meta.developer.language is
+  'The developer''s builder language (127): en, de, es, fr, nl or pt; null = English.';

package/docs/apex-feature-parity.md

@@ -23,8 +23,8 @@ Last reviewed: 2026-10-20 against **APEX 26.2** (sprint 120: the App Gallery's s
 | Data and integration | 13 | 0 | 0 | 2 | REST source catalogs from OpenAPI documents; Generate DDL and schema comparison; `meta.data_export` and data export downloads (CSV, JSON, XML, HTML, Excel, PDF); e-mail through SMTP (password or OAuth2), Microsoft Graph, Amazon SES and HTTP APIs; REST APIs via PostgREST, REST data sources that write back and synchronise, web credentials with OAuth2 grants, CSV/XLSX/JSON/XML loading with saved definitions and unloading, SQL scripts and Quick SQL, report PDFs and document templates |
 | Workflow, automation and AI | 6 | 0 | 0 | 0 | Scheduled automations with several actions and runs from SQL, approvals, a task list and workflows with parallel branches, versions and invoke-API steps; AI with Claude or OpenAI: *Generate text with AI*, an assistant region with tools, natural-language report filters and blueprints |
 | Administration | 14 | 0 | 0 | 0 | An APEX-like sign-in with a workspace and a Workspace home; a mail queue dashboard, a workspace's own mail service and network access list (26.1 / 26.2); a workspace's components exported and imported as one file; workspace message, environment banner and utilization; isolated workspaces with their own database logins and roles, and workspace administrators; application availability and Run only, automatic backups, user feedback; a developer toolbar with a session state viewer and debug per session; Top SQL per app; debug messages per request; an install/upgrade log |
-| APEX 26.2 workspace (WS-1 … WS-13) | 12 | 0 | 1 | 1 | Workspace home, Data Reporter as a workspace tool, Team Development, AI Agents, AI interactive reports, Workflow 26.2, the mail queue, workspace mail and network access, the 26.1 component details, the App Builder list's details, the Pillar navigation appearances and data security per table (rows, columns and masked values), the App Gallery's single-topic sample apps, UX Pattern Catalog and Utility Apps; not yet: the builder in more languages |
-| **Total** | **160** | **0** | **1** | **4** | 165 APEX features compared: 97% available, one missing (the open 26.2 workspace item WS-7) |
+| APEX 26.2 workspace (WS-1 … WS-13) | 13 | 0 | 0 | 1 | Workspace home, Data Reporter as a workspace tool, Team Development, AI Agents, AI interactive reports, Workflow 26.2, the mail queue, workspace mail and network access, the 26.1 component details, the App Builder list's details, the Pillar navigation appearances and data security per table (rows, columns and masked values), the App Gallery's single-topic sample apps, UX Pattern Catalog and Utility Apps; the builder in six languages |
+| **Total** | **161** | **0** | **0** | **4** | 165 APEX features compared: 98% available, none missing, 4 deliberately not planned |
 
 (Counts are of the rows in the tables below. A review on 2026-10-06 added 18 rows for APEX features that were
 not compared before, one on 2026-10-12 added two more (property help, application availability), and one on
@@ -213,7 +213,7 @@ the 26.2 comparison.)
 | Approvals and task list | ✅ | Task definitions (approval / action, owner roles and users, business administrators, priority, due date, details page), `meta.create_task` from application SQL, a task list region (claim, approve/reject/complete with comment, release, delegate, cancel, history), completion SQL in the same transaction. (sprint 64) **Vacation rules** (a stand-in acts on a user's tasks while the rule is active, checked on every request) and **expiration policies** (expire, renew up to N times, escalate to a role once; a waiting workflow goes on with the outcome `expired`). (sprint 114) **custom outcomes** with labels and colours (Yes / No / Undecided), **task events** on complete, expire and a failed completion SQL (SQL, e-mail or start a workflow; reopen or keep the task) and **notifications** from e-mail templates on create, complete and expire ([chapter 6](guide/06-processing.md#custom-outcomes)) |
 | Workflow (26.1: parallel flows, multi-tenancy) | ✅ | Workflow definitions of task, SQL, switch, wait, **invoke API** (a REST data source or URL through the invoke-API code, response values and the HTTP status into variables, retryable faults, no transaction open during the call) and end steps with variables, started from application SQL, run by the server (NOTIFY + polling) as the app's role; console region (terminate, retry a faulted step); diagram in the builder. **Parallel branches** (split, then a join that waits for all or for the first branch) and **versions** (development, active, inactive; running instances keep theirs) ([chapter 6](guide/06-processing.md#workflows)). (0.31) **Tenants**: `meta.set_tenant()` (APEX: `APEX_SESSION.SET_TENANT_ID`); workflows, their tasks, background chains, the task list, the console and every action follow the session's tenant ([chapter 6](guide/06-processing.md#tenants)). (sprint 114, 26.1 / 26.2) **Send E-Mail** steps (a template or subject and body), **draft** steps allowed only in development versions, branching on custom task outcomes, **migrating running instances** to a newer version (step mapping, preview, one transaction, a log; not yet for instances inside open parallel branches: [chapter 6](guide/06-processing.md#migrating-instances)) and the diagram as **SVG / PNG** |
 | Automations (scheduled) | ✅ | Shared Components → Automations: cron schedules with time zones, once or per row of a query, **several ordered actions** with their own conditions, **error handling** (stop, skip the row and continue, or disable; row errors in the run history), roles, run history and Run now, **on-demand runs from SQL** with `meta.run_automation()` (like `APEX_AUTOMATION.EXECUTE`, synchronous in the caller's transaction), safe with several servers ([chapter 6](guide/06-processing.md#automations)) |
-| AI assistant, natural-language reports (NL2IR), AI agents and tools (26.1) | ✅ | Region type **AI assistant**: a conversation per session, context queries (RAG over developer queries, run as the app's role, read-only), and **tools** the model may call: SQL with bound arguments checked against declared parameters (read-only unless marked as writing, row limit, timeout) and REST data sources, each optionally behind an authorization scheme. **AI Interactive Reports** (sprint 112; 26.1 / 26.2): an "Ask in your own words" box turns a question into the report's own settings (filters, highlights, search, sort, control break, totals, group by, pivot, chart and computed columns such as "bonus is 10% of salary"), never SQL, limited to its shown columns; each setting is a chip with Edit and Remove, plus Undo. Without an AI service a built-in phrase parser (English, Dutch, German) answers ([chapter 4](guide/04-pages-and-regions.md#ask-in-your-own-words-ai-interactive-reports)). Not yet: phrases mapped to faceted search and smart filter values. (sprint 111) **AI Agents** as a shared component (26.1 / 26.2): an AI service, system prompt, reasoning effort (low / medium / high, mapped per provider), approved tools, max steps and tokens and an authorization scheme; an assistant region names one. **AI Tools**: SQL (read-only transaction, the app role through RLS, timeout), PL/pgSQL function, REST data source, JavaScript action (a registered action or custom-event dynamic action), and **Navigate**: pgkiln builds the checksummed URL, only to pages the user may open. Every tool call is logged with its arguments (debug and Activity → AI usage). Providers add Gemini and OpenAI-compatible endpoints (Ollama, vLLM, Azure OpenAI). Answers are not streamed; no OCI provider. `pgvector` covers semantic search on the data side |
+| AI assistant, natural-language reports (NL2IR), AI agents and tools (26.1) | ✅ | Region type **AI assistant**: a conversation per session, context queries (RAG over developer queries, run as the app's role, read-only), and **tools** the model may call: SQL with bound arguments checked against declared parameters (read-only unless marked as writing, row limit, timeout) and REST data sources, each optionally behind an authorization scheme. **AI Interactive Reports** (sprint 112; 26.1 / 26.2): an "Ask in your own words" box turns a question into the report's own settings (filters, highlights, search, sort, control break, totals, group by, pivot, chart and computed columns such as "bonus is 10% of salary"), never SQL, limited to its shown columns; each setting is a chip with Edit and Remove, plus Undo. Without an AI service a built-in phrase parser (English, Dutch, German) answers ([chapter 4](guide/04-pages-and-regions.md#ask-in-your-own-words-ai-interactive-reports)). (sprint 122) Conditions a facet can hold set the page's **faceted search and smart filters** facets (values, excluded values, custom ranges, stars), shown as chips; smart filters with `"ask": true` read a typed phrase and offer it as one suggestion. (sprint 111) **AI Agents** as a shared component (26.1 / 26.2): an AI service, system prompt, reasoning effort (low / medium / high, mapped per provider), approved tools, max steps and tokens and an authorization scheme; an assistant region names one. **AI Tools**: SQL (read-only transaction, the app role through RLS, timeout), PL/pgSQL function, REST data source, JavaScript action (a registered action or custom-event dynamic action), and **Navigate**: pgkiln builds the checksummed URL, only to pages the user may open. Every tool call is logged with its arguments (debug and Activity → AI usage). Providers add Gemini and OpenAI-compatible endpoints (Ollama, vLLM, Azure OpenAI). Answers are not streamed; no OCI provider. `pgvector` covers semantic search on the data side |
 | *Generate Text with AI* process, structured outputs (26.1) | ✅ | **AI services** (Workspace utilities, administrators): Claude through `@anthropic-ai/sdk` or OpenAI through `openai`, encrypted write-only keys (or `ANTHROPIC_API_KEY` / `OPENAI_API_KEY`), per-app access with daily request and token limits, a usage log. Page process `ai_generate` (text into an item, or structured output into several items with a schema built from the items or your own) and a dynamic action that runs it without a page submit; `meta.ai_generate` / `ai_result` / `ai_available` from SQL ([chapter 6](guide/06-processing.md)). Prompts, item values included, go to the chosen provider |
 | Blueprints, spec-driven development (26.1) | ✅ | Create → **From a blueprint**: a JSON spec of tables (types, required, unique, allowed values, references), pages, navigation and sample data; optionally drafted by AI from a description; always reviewed (problems, SQL, pages, menu) before the application is created in one transaction; saved blueprints; (sprint 66) **a blueprint from an existing application** (its tables, pages, menu and optionally sample rows, with notes on what didn't carry over) |
 
@@ -221,7 +221,7 @@ the 26.2 comparison.)
 
 | APEX | pgkiln | Notes |
 |---|---|---|
-| Developer accounts, workspace sign-in | ✅ | (sprint 61) The builder's sign-in page like APEX's: workspace (optional; it becomes the current one, a wrong one answers like a wrong password), username, password with a Show button, *Remember workspace and username*, a link to Administration. (sprint 68) **Find my workspace**: developers' e-mail addresses, and a mail with their workspaces through the builder's mail service (the same answer for every address, limited per address and IP). **Missing:** the sign-in page's language links (the builder is in English only) |
+| Developer accounts, workspace sign-in | ✅ | (sprint 61) The builder's sign-in page like APEX's: workspace (optional; it becomes the current one, a wrong one answers like a wrong password), username, password with a Show button, *Remember workspace and username*, a link to Administration. (sprint 68) **Find my workspace**: developers' e-mail addresses, and a mail with their workspaces through the builder's mail service (the same answer for every address, limited per address and IP). (sprint 121) The sign-in page's language links: Deutsch, English, Español, Français, Nederlands, Português (WS-7) |
 | Workspace home (tool cards, top apps and users, summary, workspace and system message) | ✅ | (sprint 109) `/builder/home` opens after sign-in ([chapter 3](guide/03-builder.md#workspace-home)): App Builder, SQL Workshop, Data Reporter and App Gallery cards; the workspace message edited in place; a Summary of applications, tables, developers and reporting applications; top applications, users and developers over an hour, a day or a week; a system message with the server's version and, with the optional release check (`PGKILN_RELEASE_CHECK`, off by default), *pgkiln X is available*. The App Builder moved to `/builder/apps`; `/builder` opens either, per workspace. |
 | Workspace message, environment banner, workspace utilization, preferences and extension links (Manage Service) | ✅ | (sprint 61) An **Administration** menu in the icon rail; administrators and workspace administrators set a **workspace message** (on the App Builder home) and an **environment banner** (a coloured label on every builder page of the workspace), and see **workspace utilization** (applications, pages, page views, users, static files, schema storage) ([chapter 3](guide/03-builder.md#workspace-message-and-environment-banner)). (sprint 62) **Workspace preferences**: the SQL Workshop and the applications' RESTful services (REST modules) on or off per workspace; **extension links** in an Extensions menu of the rail ([chapter 3](guide/03-builder.md#workspace-preferences)). **Missing:** the account login controls of APEX's preferences (pgkiln's password policy and sign-in throttling are installation-wide) |
 | Instance administration, install/upgrade logs (26.1) | ✅ | Versioned migrations (`npm run db:migrate`), every run logged; Workspace utilities → **Installation** (administrators): server version, install and upgrade runs with errors, applied migrations, and warnings for migrations the database misses or the server doesn't know ([chapter 3](guide/03-builder.md)). Workspace utilities → **Instance settings**: session length and sign-in throttling (stored in the database, over the environment variables) and an overview of the server's configuration without secrets; a server whose database lacks migrations says so (503) or applies them (`MIGRATE_ON_START`). Other settings stay environment variables |
@@ -247,10 +247,10 @@ row above where there is one.
 | WS-2 Data Reporter as a workspace tool for business users | ✅ | (sprint 110) App Builder → Data Reporter: datasets, reporting applications with editors and viewers, published reports with stable URLs ([Data and integration](#data-and-integration)) |
 | WS-3 Team Development: issues, labels, milestones, templates | ✅ | (sprint 113) Builder → Team Development with a board and a set-up wizard ([App Builder and development](#app-builder-and-development)) |
 | WS-4 AI Agents with tools | ✅ | (sprint 111) AI Agents and AI Tools as shared components, a Navigate tool, Gemini and OpenAI-compatible services ([Workflow, automation and AI](#workflow-automation-and-ai)) |
-| WS-5 AI interactive reports: chips, computed columns | ✅ | (sprint 112) *Ask in your own words* with chips, Undo and computed columns; a phrase parser that needs no AI service. Not yet: phrases mapped to facets and smart filters |
+| WS-5 AI interactive reports: chips, computed columns | ✅ | (sprint 112) *Ask in your own words* with chips, Undo and computed columns; a phrase parser that needs no AI service; (sprint 122) phrases set faceted search and smart filter facets |
 | WS-6 Workflow 26.2: outcomes, migrating running instances, drafts, diagram export | ✅ | (sprint 114) Custom task outcomes, task events, Send E-Mail and draft steps, migrating running instances, the diagram as SVG / PNG ([Workflow, automation and AI](#workflow-automation-and-ai)) |
-| WS-7 The builder in more languages | ❌ | Applications have twenty-two built-in languages; the builder and its sign-in page are English only |
-| WS-8 App Gallery: more sample apps, Utility Apps | ✅ | (sprint 120) Four tabs with counts and a search that also works without JavaScript ([chapter 3](guide/03-builder.md#app-gallery)). *Sample Apps*: HR Demo, Tasks, six single-topic apps (Sample Charts, Sample Cards, Sample Calendar, Sample Interactive Grids, Sample Dynamic Actions, Sample Reporting) and the **UX Pattern Catalog**, each with its own schema, data, demo account and explanatory texts, installed by administrators from one SQL file in one transaction; *Utility Apps*: Lookup Lists, Release Notes and Announcements as blueprints any developer installs into the workspace. APEX's 27 sample apps include topics pgkiln shows in HR Demo instead (maps, approvals, workflows, REST); no remote catalogue |
+| WS-7 The builder in more languages | ✅ | (sprint 121) The builder in Deutsch, English, Español, Français, Nederlands and Português: links on the sign-in page, a language menu in the status bar, the choice stored per developer (migration 127). Translated: the builder's frame, sign-in page, Workspace home, App Builder home, an application's home and tabs, the Page Designer's toolbar, menus, tree and gallery, the SQL Workshop's home and tabs; other screens move over incrementally (English until then). Builder texts are keyed message files with a coverage check in CI |
+| WS-8 App Gallery: more sample apps, Utility Apps | ✅ | (sprint 120) Four tabs with counts and a search that also works without JavaScript ([chapter 3](guide/03-builder.md#app-gallery)). *Sample Apps*: HR Demo, Tasks, ten single-topic apps (Sample Charts, Sample Cards, Sample Calendar, Sample Interactive Grids, Sample Dynamic Actions, Sample Reporting; sprint 122: Sample Maps, Sample Approvals, Sample Data Loading, Sample Files) and the **UX Pattern Catalog**, each with its own schema, data, demo account and explanatory texts, installed by administrators from one SQL file in one transaction; *Utility Apps*: Lookup Lists, Release Notes and Announcements as blueprints any developer installs into the workspace. APEX's 27 sample apps include topics pgkiln shows in HR Demo instead (REST, trees, collections); no remote catalogue |
 | WS-9 Mail queue reporting, workspace SMTP, workspace network ACLs | ✅ | (sprint 118) Administration → Mail queue (per hour and per workspace / application, the slowest provider calls, failures with the provider's answer, Retry and Purge), a workspace's own mail service, and a workspace's network access list that narrows the installation's allow-list for every outgoing call ([Administration](#administration)) |
 | WS-10 Universal Theme 26.2: Pillar appearances, navigation polish | ✅ | (sprint 117) Theme Roller → Navigation appearance Pillar Light / Pillar Dark per application or style, with a header strip colour for light and dark mode; the current page filled, its parents bold with an accent guide line; `u-color-*-subtle` utilities; a lighter processing indicator; RTL mirrored |
 | WS-11 26.1 component details: infinite scrolling LOVs, Wait Popup, dynamic actions on menu entries | ✅ | (sprint 115) Popup LOVs that load on scroll, Wait Popup dynamic actions, the *Menu entry chosen* event ([Items](#items), [Logic and processing](#logic-and-processing)) |

package/docs/guide/03-builder.md

@@ -237,7 +237,7 @@ Every builder page has the same frame, modelled on an IDE:
   API, Settings, Search and Advisor, with Export and Run on the right.
 
 - **The status bar** at the bottom: who is signed in, the current [workspace](#workspaces), the database, the
-  builder's language and the pgkiln version.
+  [builder language](#choosing-the-builder-language) (a menu) and the pgkiln version.
 - **An environment banner** (when the current workspace has one) across the top: a coloured band with a label such as
   DEVELOPMENT or TEST, so nobody mistakes one environment for another.
 
@@ -257,6 +257,27 @@ application of a workspace you are not a member of) shows a **Page not found** p
 theme with a link to the App Builder home; a server error shows **Something went wrong** (the error
 is in the server log, not on the page). Scripts get the plain answers they always got.
 
+### Choosing the builder language
+
+(sprint 121, APEX: the builder's language links) The builder speaks **Deutsch, English, Español, Français, Nederlands
+and Português** (Brazilian). English is the default.
+
+- **On the sign-in page** the languages are links under the form: choosing one shows the sign-in page in that
+  language and, when you then sign in, stores it as your builder language. The choice is remembered on this device
+  (a cookie), so the sign-in page keeps it after you sign out.
+- **When signed in**, the language in the status bar at the bottom is a menu: pick another language and the page
+  you are on comes back in it.
+
+The language is stored **per developer** (in your developer account), so it follows you to every session and every
+device; other developers keep their own. It only changes the builder: your applications have their own languages
+(chapter 7).
+
+What is translated: the builder's frame (the rail, the top bar and its search, your account menu, the status bar,
+standard messages and error pages), the sign-in page, the Workspace home, the App Builder home, an application's
+home page and its tabs, the Page Designer's toolbar, menus, component tree, panes and gallery, and the SQL Workshop's
+home page and tabs. Other builder pages are still in English (they move over screen by screen); so are the
+Page Designer's property names and their help, the links to this guide, and any SQL the builder generates.
+
 ## Workspace home
 
 (sprint 109; APEX: the workspace home page) The page the builder opens after signing in, `/builder/home`, above the
@@ -346,8 +367,14 @@ server, `?q=`); every word must be in the title or the description.
     four views, create on click, drag and drop through a function), **Sample Interactive Grids** (an editable grid,
     select lists, totals, a frozen column, a row menu, master-detail, the grid's views), **Sample Dynamic Actions**
     (show and hide, values from the server, refresh, messages, a wait popup, classes, an inline dialog) and
-    **Sample Reporting** (interactive report, faceted search, smart filters, a classic report with column options and
-    a column template);
+    **Sample Reporting** (interactive report, faceted search, smart filters that also read a phrase, a classic report
+    with column options and a column template); and (sprint 122; APEX: Sample Maps, Sample Approvals, Sample Data
+    Loading, Sample File Upload and Download) **Sample Maps** (markers and clusters, layers with GeoJSON and a heat
+    map, a map that filters a list by distance, a location item, without PostGIS), **Sample Approvals** (a form
+    starts a workflow: approved by itself below 1,000, otherwise an approval task decided under My tasks; the
+    workflow console; accounts **demo** and **approver**), **Sample Data Loading** (`data_load` processes by column
+    name, through a data load definition and skipping bad rows, with example files to download) and **Sample Files**
+    (a file in the record's columns, several files in a child table, a photo cropped before upload);
   - the **UX Pattern Catalog** (APEX: the Universal Theme app): region templates and template options, button
     styles, item types and form layouts, alerts, badges, colour classes, lists, media lists, timelines, comments,
     avatars, metric cards, empty states, a dialog, a drawer and a side column, each named by its template, option

package/docs/guide/04-pages-and-regions.md

@@ -312,6 +312,23 @@ klerken*, *bonus is 10% van salaris*) and German (*Gehalt über 3000*, *sortiere
 absteigend*, *Summe von Gehalt pro Abteilung*, *nur Angestellte*) work the same way; another
 language adds a phrase table to `src/runtime/ir-phrases.ts`.
 
+**With faceted search or smart filters** on the same report (sprint 122; APEX 26.2), a condition
+that one of their facets can hold sets **that facet** instead of becoming a report filter, so the
+facet panel or the smart filter chips show it and the facet counts follow. The facets' selections
+are chips of the box too (with Remove; the facet region edits them), and Undo and *start over*
+include them:
+
+| Condition | Facet |
+|---|---|
+| *only clerks*, *clerks and analysts* (equals) | a checkbox facet: its values |
+| *not clerks* (differs from) | a checkbox facet with `exclude`: the value, excluded |
+| *salary between 1000 and 3000*, *at least 2000*, *hired in 1981* | a range facet with custom ranges (`custom`): from / to |
+| *rating at least 4* | a star facet: *4 stars & up* |
+
+Anything else (*salary over 3000*, *name contains*, a column without a facet) stays a report
+filter. Only facets of regions the user sees count. A smart filters region can also read its own
+search field this way (`"ask": true`, [below](#smart_filters)).
+
 **With an AI service** (`"ai_filter": {"service": "NAME"}`, an [AI
 service](06-processing.md#generate-text-with-ai) the application may use), the request goes to the
 service with the report's shown columns (names, headings and kinds: text, number, date, boolean),
@@ -950,6 +967,15 @@ that filter. If nothing matches, the term searches all columns of the report.
 | `facets` | As for [`facets`](#facets-faceted-search) (checkbox, range and star; `exclude` and `custom` are for the facets panel) |
 | `suggestions` | Suggestions per facet, 0–10 (default 3) |
 | `placeholder` | The text in the empty search field (translatable) |
+| `ask` | `true`: also read the search text as a phrase (sprint 122; APEX 26.2) |
+
+With `"ask": true` the text typed in the search field is also read as a phrase, with the built-in
+phrases of [*Ask in your own words*](#ask-in-your-own-words-ai-interactive-reports) (no AI service
+needed): *"clerks in sales with salary between 1000 and 3000"*, *"not clerks, salary at least
+2000"*. What the region's facets can hold is offered as the first suggestion, **Understood as:**
+*Job: CLERK · Department: SALES · Salary: 1000 – 3000*; choosing it sets those facets and clears the
+search. Values are looked up in the report's own rows (as query parameters). A single value
+(*"clerk"*) stays the ordinary matching suggestion.
 
 Everything is a link or a GET form on the report's own URL parameters, so it works without
 JavaScript, can be bookmarked and is kept in saved reports. A facets panel and smart filters may

package/docs/guide/12-development.md

@@ -263,6 +263,11 @@ src/
   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
+    i18n.ts                (sprint 121) the builder's own texts: BUILDER_LANGUAGES, tr(s) / translatorFor(lang) → tx(key, params),
+                           tx.rich (markup in a sentence), tx.dyn (keys made at run time), tx.label (known breadcrumb labels)
+    i18n/                  en.ts defines the builder's keys; de, es, fr, nl, pt are Records of the same keys
+    language.ts            (migration 127) the status bar's language menu (POST /builder/language), the sign-in page's
+                           language links (?lang=, a cookie), meta.developer.language
     routes.ts              sign-in, app home, settings, activity, developers, create (POST, via newapp.ts)/import (POST)
     wizards.ts             create page wizards: step 2 forms per page type (defaults from meta.wizard_defaults), POST → meta.generate_page
                            (the generators are PL/pgSQL in migration 047: catalog, defaults, form/cards/calendar/chart/map/facets/master-detail)
@@ -484,6 +489,8 @@ test/
   logic.test.ts            computations, branches, menu buttons and badges, new dynamic actions, build options, export
   page-logic.test.ts       download, chain (background jobs) and workflow processes, function/app branches, dialog_closed (HR page 28)
   code-editor.test.ts      code editor: completions scoped to the app's role, the check, marked fields
+  builder-i18n.test.ts     (sprint 121) builder languages: the coverage check of src/builder against i18n/en.ts, the message
+                           files, Deutsch on the sign-in page, the status bar menu, the choice per developer, English fallback
   builder-home.test.ts     App Builder home: search, sort, views, Recent, Create/Import pages, dashboard, utilities
   app-list.test.ts         (116) the App Builder list's Updated by, working copies and lock; what counts as a change
   import-only.test.ts      (116) pgkiln import --replace --only: a page or component file, refusals
@@ -531,6 +538,7 @@ test/
   ai-mock.ts               a local mock of the Claude Messages API (SSE stream) and OpenAI Chat Completions
   helpers.ts               a cookie-keeping test browser
   e2e/responsive.test.ts   browser tests at phone/tablet/desktop widths (Playwright)
+  e2e/builder-i18n.test.ts (sprint 121) Deutsch on the sign-in page, the status bar's language menu, German screens at 390 px, CSP
   e2e/gallery.test.ts      (sprint 120) the gallery's sample apps: every page at 4 widths, CSP, axe; dynamic actions; the four tabs at 390 px
   e2e/admin-mail-network.test.ts (sprint 118) Mail queue, Network access and a workspace's mail service at 390 px without JavaScript
   e2e/pillar.test.ts       (sprint 117) Pillar appearances: axe in light and dark, subtle colours, current vs parent entry, Arabic RTL, 390 px, preview
@@ -551,6 +559,39 @@ test/
   e2e/ai.test.ts           Generate text with AI on HR page 37 in a browser (mock Claude): dynamic actions without a submit, errors, no JavaScript
 ```
 
+## Builder texts in more languages
+
+(sprint 121) The builder's own texts are keyed messages, like the runtime's: `src/builder/i18n/en.ts` defines every
+key (`<screen>.<what>`, e.g. `rail.app_builder`, `pd.menu.create`, `ab.count` with `{n}`), and `de.ts`, `es.ts`,
+`fr.ts`, `nl.ts` and `pt.ts` are `Record<BuilderKey, string>` of the same keys. A page takes its translator from the
+session and uses it for every text it shows:
+
+```ts
+const tx = tr(s);                                  // the developer's language (meta.developer.language, in the session)
+html`<h2>${tx('wh.summary')}</h2><p>${tx('ab.count', { n: 3 })}</p>`;   // plain text: html`` escapes it
+tx.rich('ab.none_yet', { create: html`<a href="…">${tx('ab.create_one')}</a>` });   // markup inside a sentence
+tx.dyn(`gallery.region.${type}`, REGION_LABELS[type][0]);              // a key made at run time, with a fallback
+```
+
+A missing text falls back to English, never to the raw key. Shared helpers that render chrome take the session as
+an optional last argument (`appHeader(a, 'pages', s)`, `workshopTabs('sql', s)`); `shell()` translates known English
+breadcrumb labels (`tx.label`) so pages that aren't moved yet still get a translated trail.
+
+**Moving a screen over**: replace its literal texts with `tx('key')`, add each key with its English text to `en.ts`
+(keep the English exactly as it was: tests and e2e tests assert it), then add the key to the five other files
+(TypeScript refuses a file with a missing or an unknown key). A sentence with a link is one key with a `{link}`
+placeholder and `tx.rich`, not pieces glued together; a count has a `_one` and a plural key; never lower-case a
+translated label (German nouns). Flash messages are translated where they are set.
+
+**The coverage check** (`test/builder-i18n.test.ts`, part of `npm test` and CI) scans `src/builder/**/*.ts` for
+`tx('…')`, `tx.rich('…')` and `tr(s)('…')` and fails when a key has no English text (templated keys such as
+`` `ago.${unit}` `` must match at least one English key); checks that every region type, item type, button action,
+display position, button position, component kind and SQL Workshop tool has its run-time key; and that every
+language file has exactly the English keys, the same `{placeholders}`, no empty texts and is mostly translated.
+
+Stays English by design: the property editor's field names and help, links to the guide, generated SQL, and pages
+not moved yet. The builder's language is separate from an application's languages (`src/i18n.ts`).
+
 ## Principles
 
 - **User-facing texts go through the translator**: `ctx.locale.t('key')` for pgkiln's own texts (add the key to `en` and `nl` in `src/i18n.ts` and to `src/i18n/de.ts`, `fr.ts`, `es.ts`; TypeScript checks that every language has every key), `ctx.locale.tr(text)` for texts derived from application metadata.

package/examples/gallery/README.md

@@ -23,6 +23,10 @@ The builder's **App Gallery** (`/builder/gallery`) lists what `gallery.json` nam
 | `sample-grids.sql` | Sample Interactive Grids | an editable grid, select lists, totals, frozen column, row menu, master-detail, views |
 | `sample-dynamic-actions.sql` | Sample Dynamic Actions | show/hide/enable, set value, refresh, messages, wait popup, classes, inline dialog |
 | `sample-reporting.sql` | Sample Reporting | interactive report, faceted search, smart filters, a classic report with column options |
+| `sample-maps.sql` | Sample Maps | markers and clusters, layers with GeoJSON and a heat map, a map filtering a list by distance, a location item |
+| `sample-approvals.sql` | Sample Approvals | a workflow started by a form, an approval task and the task list, the workflow console (accounts demo and approver) |
+| `sample-data-loading.sql` | Sample Data Loading | `data_load` processes: by column name and merged, through a data load definition, skipping rows with errors |
+| `sample-files.sql` | Sample Files | a file in the record's columns, several files in a child table, a photo cropped before upload |
 | `ux-patterns.sql` | UX Pattern Catalog | region templates and options, buttons, items and form layouts, content and page patterns |
 
 Each script creates its own schema (`sample_charts`, …), a role (`app_sample_charts`, …) granted to the runtime, the

package/examples/gallery/gallery.json

@@ -16,6 +16,14 @@
      "description": "Behaviour without JavaScript of your own: show, hide, enable on a condition; values computed on the server; a report refreshed when an item changes; alerts, confirmations, a wait popup, classes, item errors and an inline dialog. Demo account demo / demo."},
     {"key": "sample-reporting", "title": "Sample Reporting", "alias": "sample-reporting", "icon": "file-text", "file": "samples/sample-reporting.sql",
      "description": "Reports and the ways to search them: an interactive report with its form, a faceted search, smart filters, and a classic report with column display options, a column template and a link. Demo account demo / demo."},
+    {"key": "sample-maps", "title": "Sample Maps", "alias": "sample-maps", "icon": "map", "file": "samples/sample-maps.sql",
+     "description": "Maps of Dutch museums without PostGIS: markers with popups and clustering, several layers (a route and an area as GeoJSON, a heat map you switch on), a map that filters the list beside it by distance, and a form with a location item. Demo account demo / demo."},
+    {"key": "sample-approvals", "title": "Sample Approvals", "alias": "sample-approvals", "icon": "list-checks", "file": "samples/sample-approvals.sql",
+     "description": "Purchase requests that start a workflow: approved by itself below 1,000, otherwise an approval task for the role approver, decided under My tasks; the workflow console with its diagram and history. Demo accounts demo / demo (asks) and approver / approver (decides)."},
+    {"key": "sample-data-loading", "title": "Sample Data Loading", "alias": "sample-data-loading", "icon": "file-up", "file": "samples/sample-data-loading.sql",
+     "description": "Loading CSV, Excel and JSON files into a table from a page: merged by the key, through a data load definition that maps other headings and a date format, and skipping rows with errors. Example files to download included. Demo account demo / demo."},
+    {"key": "sample-files", "title": "Sample Files", "alias": "sample-files", "icon": "files", "file": "samples/sample-files.sql",
+     "description": "File upload and download: a file in the record's own column with its name, type, size and date, several files per record in a child table, and a photo cropped square before upload. Demo account demo / demo."},
     {"key": "ux-patterns", "title": "UX Pattern Catalog", "alias": "ux-patterns", "icon": "palette", "file": "samples/ux-patterns.sql",
      "description": "The theme's building blocks to copy from: region templates and template options, button styles, item types and form layouts, alerts, badges, colour classes, lists, media lists, timelines, comments, avatars, metric cards, empty states, dialogs, drawers and side columns. Demo account demo / demo."}
   ],

package/examples/gallery/samples/sample-approvals.sql

@@ -0,0 +1,153 @@
+-- =====================================================================
+-- Sample app "Sample Approvals" (App Gallery → Sample Apps)
+--
+-- Approvals, the task list and a workflow on purchase requests:
+--   * a request is made on a form; creating it starts the PURCHASE workflow
+--   * below 1,000 the workflow approves it by itself (an SQL step)
+--   * from 1,000 it asks for approval: a PURCHASE_APPROVAL task for the
+--     users with the role approver, decided under My tasks; the task's
+--     action records the decision on the request
+--   * the console lists the workflows with their diagram and history
+--
+-- Two accounts: demo / demo asks, approver / approver decides (nobody
+-- approves their own request).
+--
+-- Installed by an administrator from the App Gallery, or with
+--   psql "$DATABASE_URL" -1 -f examples/gallery/samples/sample-approvals.sql
+-- then open /a/sample-approvals and sign in as demo / demo.
+-- =====================================================================
+
+create or replace function pg_temp.page_id(p_alias text, p_page int) returns int language sql stable as
+  $$ select p.id from meta.page p join meta.app a on a.id = p.app_id where a.alias = p_alias and p.page_no = p_page $$;
+
+-- 1. Schema and data ---------------------------------------------------------
+create schema sample_approvals;
+
+create table sample_approvals.purchase (
+  id           int generated always as identity primary key,
+  title        text not null,
+  supplier     text,
+  amount       numeric(10, 2) not null check (amount > 0),
+  status       text not null default 'PENDING' check (status in ('PENDING', 'APPROVED', 'REJECTED')),
+  requested_by text,
+  requested_at timestamptz not null default now(),
+  decided_by   text,
+  note         text
+);
+
+-- who asked, and that a new request is pending, come from the session, not the form
+create function sample_approvals.purchase_defaults() returns trigger language plpgsql as $$
+begin
+  new.requested_by := coalesce(meta.app_user(), current_user);
+  new.status := 'PENDING';
+  new.decided_by := null;
+  return new;
+end
+$$;
+create trigger purchase_defaults before insert on sample_approvals.purchase
+  for each row execute function sample_approvals.purchase_defaults();
+
+-- the decision, from the approval task's action (by the approver) or the workflow's SQL step
+-- (which runs as the user who started the workflow, so it says who decided: 'workflow')
+create function sample_approvals.decide(p_id int, p_outcome text, p_note text, p_by text default null) returns void language plpgsql as $$
+begin
+  update sample_approvals.purchase
+     set status = case lower(p_outcome) when 'approved' then 'APPROVED' when 'rejected' then 'REJECTED' else status end,
+         decided_by = coalesce(p_by, meta.app_user()), note = nullif(p_note, '')
+   where id = p_id and status = 'PENDING';
+end
+$$;
+
+insert into sample_approvals.purchase (title, supplier, amount) values
+  ('Printer toner', 'Office Supplies Ltd', 89.50), ('Standing desks (4)', 'ErgoWorks', 2400.00), ('Team lunch', 'De Kantine', 160.00);
+update sample_approvals.purchase set status = 'APPROVED', requested_by = 'demo', decided_by = 'workflow', note = 'Below 1,000: approved automatically' where title in ('Printer toner', 'Team lunch');
+update sample_approvals.purchase set status = 'APPROVED', requested_by = 'demo', decided_by = 'approver', note = 'Within the budget' where title = 'Standing desks (4)';
+
+-- 2. The application's database role ----------------------------------------
+do $$ begin
+  if not exists (select 1 from pg_roles where rolname = 'app_sample_approvals') then create role app_sample_approvals nologin; end if;
+end $$;
+grant app_sample_approvals to pgkiln_runtime;
+grant usage on schema sample_approvals to app_sample_approvals;
+grant select, insert, update, delete on sample_approvals.purchase to app_sample_approvals;
+grant execute on function sample_approvals.decide(int, text, text, text) to app_sample_approvals;
+
+-- 3. The application ----------------------------------------------------------
+insert into meta.app (alias, name, home_page, authentication, db_role)
+values ('sample-approvals', 'Sample Approvals', 1, 'app_users', 'app_sample_approvals');
+
+insert into meta.app_user (app_id, username, password_hash, roles)
+select a.id, u.name, meta.hash_password(u.name), u.roles
+  from meta.app a, (values ('demo', '{}'::text[]), ('approver', '{approver}'::text[])) as u (name, roles)
+ where a.alias = 'sample-approvals';
+
+insert into meta.task_definition (app_id, name, type, subject, owner_roles, admin_role, priority, due_in, details_page, details_item, action_code)
+select id, 'PURCHASE_APPROVAL', 'approval', 'Purchase: &TITLE. (&AMOUNT.)', '{approver}'::text[], 'approver', 2, '3 days', 3, 'P3_ID',
+       'select sample_approvals.decide(:DETAIL_PK::int, :OUTCOME, :COMMENT)'
+  from meta.app where alias = 'sample-approvals';
+
+insert into meta.workflow_definition (app_id, name, title, description, admin_role, steps)
+select id, 'PURCHASE', 'Purchase: &TITLE.', 'A purchase request: approved by itself below 1,000, otherwise by an approver.', 'approver',
+$s$[
+  {"name": "AMOUNT_CHECK", "type": "switch", "cases": [{"when": ":AMOUNT::numeric >= 1000", "next": "APPROVE"}], "otherwise": "AUTO_APPROVE"},
+  {"name": "AUTO_APPROVE", "type": "sql", "code": "select sample_approvals.decide(:DETAIL_PK::int, 'approved', 'Below 1,000: approved automatically', 'workflow')", "next": "END"},
+  {"name": "APPROVE", "type": "task", "task": "PURCHASE_APPROVAL"},
+  {"name": "END", "type": "end"}
+]$s$::jsonb
+  from meta.app where alias = 'sample-approvals';
+
+insert into meta.page (app_id, page_no, name, title, parent_page)
+select a.id, p.no, p.name, p.name, p.parent
+  from meta.app a, (values (1, 'Sample Approvals', null), (4, 'My tasks', 1), (5, 'Workflows', 1)) as p (no, name, parent)
+ where a.alias = 'sample-approvals';
+
+-- page 2 and its form, page 3: the Report and form wizard on the requests
+select meta.generate_page('sample-approvals', 'report_form', 'sample_approvals.purchase', 2, '{"label": "Purchases", "form_page": 3, "nav": false}');
+update meta.page set parent_page = 1 where app_id = (select id from meta.app where alias = 'sample-approvals') and page_no = 2;
+update meta.region set source = 'select id, title, supplier, amount, status, requested_by, decided_by, note from sample_approvals.purchase order by id desc',
+       config = config || '{"formats": {"amount": "999G999G990D00"}}'
+ where page_id = pg_temp.page_id('sample-approvals', 2) and type = 'report';
+-- the form asks only what the requester decides; the rest is shown, not edited
+update meta.item set type = 'display'
+ where page_id = pg_temp.page_id('sample-approvals', 3) and name in ('P3_STATUS', 'P3_REQUESTED_BY', 'P3_REQUESTED_AT', 'P3_DECIDED_BY', 'P3_NOTE');
+
+-- creating a request starts the workflow, after the row is inserted (P3_ID is then known)
+insert into meta.process (page_id, seq, name, type, code, when_button)
+select pg_temp.page_id('sample-approvals', 3), 15, 'Start the approval', 'sql',
+       $c$select meta.start_workflow('PURCHASE', :P3_ID, jsonb_build_object('TITLE', :P3_TITLE, 'AMOUNT', :P3_AMOUNT))$c$, 'CREATE';
+
+insert into meta.nav_entry (app_id, seq, label, icon, target_page)
+select a.id, n.seq, n.label, n.icon, n.page
+  from meta.app a, (values (10, 'Home', 'home', 1), (20, 'Purchases', 'list', 2), (30, 'My tasks', 'check', 4), (40, 'Workflows', 'route', 5)) as n (seq, label, icon, page)
+ where a.alias = 'sample-approvals';
+
+insert into meta.list (app_id, name, type, description)
+select id, 'APPROVAL_TOPICS', 'static', 'The pages of Sample Approvals' from meta.app where alias = 'sample-approvals';
+
+insert into meta.list_entry (app_id, list_name, seq, label, icon, target_page, description)
+select a.id, 'APPROVAL_TOPICS', e.seq, e.label, e.icon, e.page, e.description
+  from meta.app a, (values
+  (10, 'Purchases', 'list', 2, 'Ask for a purchase: creating it starts the PURCHASE workflow.'),
+  (20, 'My tasks', 'check', 4, 'Approve or reject what waits for you, and follow what you asked for.'),
+  (30, 'Workflows', 'route', 5, 'The workflows you started, with their diagram, current step and history.')
+  ) as e (seq, label, icon, page, description)
+ where a.alias = 'sample-approvals';
+
+insert into meta.region (page_id, seq, title, type, columns, template, source, config)
+select pg_temp.page_id('sample-approvals', r.page), r.seq, r.title, r.type, 12, r.template, r.source, r.config::jsonb
+  from (values
+  (1, 10, 'Sample Approvals', 'static', 'hero',
+   '<p>Signed in as <strong>demo</strong>, ask for a purchase under <em>Purchases</em>. Below 1,000 the workflow approves it at once; from 1,000 it creates an approval task for the role <code>approver</code>. Sign in as <strong>approver</strong> / approver and decide under <em>My tasks</em>: the task''s action writes the decision on the request, and the workflow ends.</p>',
+   '{"icon": "check"}'),
+  (1, 20, 'Topics', 'list', 'plain', null, '{"list": "APPROVAL_TOPICS", "template": "cards"}'),
+  (2, 5, 'About this page', 'static', 'plain',
+   '<p class="lead">The form''s Create button runs the wizard''s row process, then <code>select meta.start_workflow(''PURCHASE'', :P3_ID, …)</code>. A trigger fills in who asked and the status from the session, so the form can''t set them.</p>', '{}'),
+  (4, 5, 'About this page', 'static', 'plain',
+   '<p class="lead">Regions of type <code>tasks</code>: what waits for the signed-in user (as owner, here the role <code>approver</code>), and what they asked for. Approve and Reject run the task definition''s action with <code>:DETAIL_PK</code>, <code>:OUTCOME</code> and <code>:COMMENT</code>.</p>', '{}'),
+  (4, 10, 'Waiting for me', 'tasks', 'standard', null, '{"empty": "Nothing waits for you. Sign in as approver to decide on requests of 1,000 or more."}'),
+  (4, 20, 'Requested by me', 'tasks', 'collapsible', null, '{"context": "initiated", "completed": true, "empty": "You have not asked for anything that needs approval."}'),
+  (5, 5, 'About this page', 'static', 'plain',
+   '<p class="lead">A region of type <code>workflows</code>: the workflows the user started, or with <code>"context": "admin"</code> those they administer (here: approver). Open one for its diagram, current step and history; the initiator and administrators can terminate it.</p>', '{}'),
+  (5, 10, 'Workflows I started', 'workflows', 'standard', null, '{"completed": true}'),
+  (5, 20, 'All purchase workflows (approvers)', 'workflows', 'collapsible', null, '{"context": "admin", "completed": true}')
+  ) as r (page, seq, title, type, template, source, config);

package/examples/gallery/samples/sample-data-loading.sql

@@ -0,0 +1,142 @@
+-- =====================================================================
+-- Sample app "Sample Data Loading" (App Gallery → Sample Apps)
+--
+-- Loading CSV, Excel, JSON and XML files into a table from a page: a load
+-- that matches columns by name and merges by the primary key; a load
+-- through a data load definition that maps other headings, cleans values
+-- and reads a date format; and a load that skips rows with errors and lists
+-- them. The example files are static files of the application.
+--
+-- Installed by an administrator from the App Gallery, or with
+--   psql "$DATABASE_URL" -1 -f examples/gallery/samples/sample-data-loading.sql
+-- then open /a/sample-data-loading and sign in as demo / demo.
+-- =====================================================================
+
+create or replace function pg_temp.page_id(p_alias text, p_page int) returns int language sql stable as
+  $$ select p.id from meta.page p join meta.app a on a.id = p.app_id where a.alias = p_alias and p.page_no = p_page $$;
+
+-- 1. Schema and data ---------------------------------------------------------
+create schema sample_loading;
+
+create table sample_loading.product (
+  code     text primary key check (code ~ '^[A-Z]{2}-\d{3}$'),
+  name     text not null,
+  category text not null check (category in ('TOOLS', 'GARDEN', 'KITCHEN', 'OFFICE')),
+  price    numeric(8, 2) not null check (price > 0),
+  stock    int not null default 0 check (stock >= 0),
+  added    date not null default current_date
+);
+
+insert into sample_loading.product (code, name, category, price, stock, added) values
+  ('TL-001', 'Hammer', 'TOOLS', 14.95, 40, '2026-01-12'),
+  ('TL-002', 'Screwdriver set', 'TOOLS', 19.50, 25, '2026-01-12'),
+  ('GD-001', 'Garden hose 20 m', 'GARDEN', 24.99, 12, '2026-03-02'),
+  ('KT-001', 'Chef''s knife', 'KITCHEN', 39.00, 8, '2026-04-20');
+
+-- 2. The application's database role ----------------------------------------
+do $$ begin
+  if not exists (select 1 from pg_roles where rolname = 'app_sample_loading') then create role app_sample_loading nologin; end if;
+end $$;
+grant app_sample_loading to pgkiln_runtime;
+grant usage on schema sample_loading to app_sample_loading;
+grant select, insert, update, delete on sample_loading.product to app_sample_loading;
+
+-- 3. The application ----------------------------------------------------------
+insert into meta.app (alias, name, home_page, authentication, db_role)
+values ('sample-data-loading', 'Sample Data Loading', 1, 'app_users', 'app_sample_loading');
+
+insert into meta.app_user (app_id, username, password_hash, roles)
+select id, 'demo', meta.hash_password('demo'), '{}' from meta.app where alias = 'sample-data-loading';
+
+-- the example files, served at /a/sample-data-loading/static/<name>
+insert into meta.static_file (app_id, name, mime, content)
+select a.id, f.name, f.mime, convert_to(f.body, 'utf8')
+  from meta.app a, (values
+  ('products.csv', 'text/csv',
+   E'code,name,category,price,stock\nTL-002,Screwdriver set,TOOLS,17.95,30\nTL-003,Spirit level,TOOLS,12.50,15\nOF-001,Stapler,OFFICE,8.95,60\nOF-002,Desk lamp,OFFICE,29.00,10\n'),
+  ('products.json', 'application/json',
+   E'[{"code": "KT-002", "name": "Cutting board", "category": "KITCHEN", "price": 15.5, "stock": 20},\n {"code": "GD-002", "name": "Pruning shears", "category": "GARDEN", "price": 21.95, "stock": 9}]\n'),
+  ('supplier-list.csv', 'text/csv',
+   E'Article no.,Description,Group,Unit price,In stock,Since\ngd-003,  watering   can ,garden,9.99,35,02.05.2026\nkt-003,kitchen   scale,Kitchen,18.75,14,15.06.2026\n'),
+  ('with-errors.csv', 'text/csv',
+   E'code,name,category,price,stock\nOF-003,Notebook,OFFICE,3.50,100\nOF-004,Paper clips,OFFICE,-1,500\nXX,Mystery box,TOYS,10,1\nOF-005,Pencil case,OFFICE,6.25,40\n')
+  ) as f (name, mime, body)
+ where a.alias = 'sample-data-loading';
+
+-- other headings, messy values, a date format: a data load definition (Shared Components → Data load definitions)
+insert into meta.data_load_def (app_id, name, description, table_name, format, mode, columns)
+select a.id, 'SUPPLIER_LIST', 'A supplier''s product list: other headings, codes and groups in lower case, dates as DD.MM.YYYY.',
+       'sample_loading.product', 'csv', 'merge',
+       '[{"source": "Article no.", "column": "code", "transform": ["trim", "upper"]},
+         {"source": "Description", "column": "name", "transform": ["collapse_spaces", "initcap"]},
+         {"source": "Group", "column": "category", "transform": ["trim", "upper"]},
+         {"source": "Unit price", "column": "price", "format": "99990.99"},
+         {"source": "In stock", "column": "stock", "default": "0"},
+         {"source": "Since", "column": "added", "format": "DD.MM.YYYY"}]'
+  from meta.app a where a.alias = 'sample-data-loading';
+
+insert into meta.page (app_id, page_no, name, title, parent_page)
+select a.id, p.no, p.name, p.name, p.parent
+  from meta.app a, (values (1, 'Sample Data Loading', null), (2, 'Products', 1), (3, 'Load a file', 1), (4, 'Load with a definition', 1), (5, 'Skip rows with errors', 1)) as p (no, name, parent)
+ where a.alias = 'sample-data-loading';
+
+insert into meta.nav_entry (app_id, seq, label, icon, target_page)
+select a.id, n.seq, n.label, n.icon, n.page
+  from meta.app a, (values
+  (10, 'Home', 'home', 1), (20, 'Products', 'table', 2), (30, 'Load a file', 'upload', 3),
+  (40, 'Load with a definition', 'upload', 4), (50, 'Skip rows with errors', 'upload', 5)
+  ) as n (seq, label, icon, page)
+ where a.alias = 'sample-data-loading';
+
+insert into meta.list (app_id, name, type, description)
+select id, 'LOAD_TOPICS', 'static', 'The pages of Sample Data Loading' from meta.app where alias = 'sample-data-loading';
+
+insert into meta.list_entry (app_id, list_name, seq, label, icon, target_page, description)
+select a.id, 'LOAD_TOPICS', e.seq, e.label, e.icon, e.page, e.description
+  from meta.app a, (values
+  (10, 'Products', 'table', 2, 'The table the pages load into.'),
+  (20, 'Load a file', 'upload', 3, 'CSV, Excel or JSON with the table''s column names, merged by the product code.'),
+  (30, 'Load with a definition', 'upload', 4, 'Other headings, values in the wrong case and a date format, mapped by a data load definition.'),
+  (40, 'Skip rows with errors', 'upload', 5, 'Load the good rows and list the others, instead of loading nothing.')
+  ) as e (seq, label, icon, page, description)
+ where a.alias = 'sample-data-loading';
+
+insert into meta.region (page_id, seq, title, type, columns, template, source, config, static_id)
+select pg_temp.page_id('sample-data-loading', r.page), r.seq, r.title, r.type, 12, r.template, r.source, r.config::jsonb, r.sid
+  from (values
+  (1, 10, 'Sample Data Loading', 'static', 'hero',
+   '<p>A page with a file item, a button and a <code>data_load</code> process loads a file into a table. It runs as the application''s database role, so grants, constraints, triggers and row level security apply as they do for a form, and by default a file with one bad row loads nothing at all.</p>',
+   '{"icon": "upload"}', null),
+  (1, 20, 'Topics', 'list', 'plain', null, '{"list": "LOAD_TOPICS", "template": "cards"}', null),
+  (2, 10, 'Products', 'report', 'standard',
+   'select code, name, category, price, stock, added from sample_loading.product order by code',
+   '{"formats": {"price": "999G990D00"}, "page_size": 50}', null),
+  (3, 10, 'Load a file', 'static', 'standard',
+   '<p class="lead">The process: <code>{"file_item": "P3_FILE", "table": "sample_loading.product", "mode": "merge"}</code>. Columns are matched by name; a row whose <code>code</code> exists is updated, the others are added. Try <a href="/a/sample-data-loading/static/products.csv" download>products.csv</a> (one update, three new) or <a href="/a/sample-data-loading/static/products.json" download>products.json</a>, then look at <a href="/a/sample-data-loading/2">Products</a>.</p>',
+   '{}', 'load'),
+  (4, 10, 'Load with a definition', 'static', 'standard',
+   '<p class="lead"><a href="/a/sample-data-loading/static/supplier-list.csv" download>supplier-list.csv</a> has other headings (<em>Article no.</em>, <em>Unit price</em>), codes in lower case, extra spaces and dates as 02.05.2026. The data load definition <code>SUPPLIER_LIST</code> maps each heading to a column, trims and upper-cases the code, collapses the spaces in the name and reads the date with <code>DD.MM.YYYY</code>; the process only names it: <code>{"file_item": "P4_FILE", "definition": "SUPPLIER_LIST"}</code>.</p>',
+   '{}', 'load'),
+  (5, 10, 'Skip rows with errors', 'static', 'standard',
+   '<p class="lead"><a href="/a/sample-data-loading/static/with-errors.csv" download>with-errors.csv</a> has a negative price and a code and category the table''s check constraints refuse. With <code>"skip_errors": true</code> the two good rows are loaded and the others are listed with the database''s reason; without it (the other pages) nothing would be loaded.</p>',
+   '{}', 'load')
+  ) as r (page, seq, title, type, template, source, config, sid);
+
+insert into meta.item (page_id, region_id, seq, name, label, type, required, help, config)
+select r.page_id, r.id, 10, 'P' || p.page_no || '_FILE', 'File', 'file', true, 'CSV, Excel (.xlsx) or JSON, at most 2 MB.',
+       '{"accept": ".csv,.tsv,.txt,.xlsx,.json", "max_mb": 2, "wide": true}'
+  from meta.region r join meta.page p on p.id = r.page_id join meta.app a on a.id = p.app_id
+ where a.alias = 'sample-data-loading' and r.static_id = 'load';
+
+insert into meta.button (page_id, region_id, seq, name, label, action, hot)
+select r.page_id, r.id, 10, 'LOAD', 'Load', 'submit', true
+  from meta.region r join meta.page p on p.id = r.page_id join meta.app a on a.id = p.app_id
+ where a.alias = 'sample-data-loading' and r.static_id = 'load';
+
+insert into meta.process (page_id, seq, name, type, when_button, success_message, config)
+select pg_temp.page_id('sample-data-loading', x.page), 10, x.name, 'data_load', 'LOAD', x.message, x.config::jsonb
+  from (values
+  (3, 'Load products', '{inserted} products added, {updated} updated.', '{"file_item": "P3_FILE", "table": "sample_loading.product", "mode": "merge"}'),
+  (4, 'Load a supplier list', '{inserted} products added, {updated} updated.', '{"file_item": "P4_FILE", "definition": "SUPPLIER_LIST"}'),
+  (5, 'Load the good rows', '{inserted} added, {updated} updated, {failed} skipped.', '{"file_item": "P5_FILE", "table": "sample_loading.product", "mode": "merge", "skip_errors": true}')
+  ) as x (page, name, message, config);