pgkiln 0.70.0 → 0.72.0

package/docs/guide/03-builder.md

@@ -855,8 +855,8 @@ they are **not** run until you choose to.
 
 (sprint 74) Above the pages: a **search** by page name or number (the rows filter while you type),
 **Report** and **Icons** views, and **Create page** (the page wizards below). **Tasks** on the right: run the
-application, create pages (also with AI), Shared Components, page groups, export, backups, supporting
-objects, lock or delete the application.
+application, create pages (also with AI), (sprint 137) **Add feature page** and **Create page as copy**, Shared
+Components, page groups, export, backups, supporting objects, lock or delete the application.
 
 The **default-password** warning shows on the App Builder home (and Developers) only; dismiss it with × until the
 next sign-in. The avatar keeps a red dot until the password is changed.
@@ -867,9 +867,19 @@ authorization and protection. The tabs under its name lead to **Shared Component
 
 ### Create pages from a table (wizards)
 
-The wizards are two plain forms (they work without JavaScript). On the app's Pages tab, choose a
+(sprint 137; APEX: Create a Page) **Create page** opens a page with three tabs:
+
+- **Component**: the page types as a grid of tiles, each with a small picture of the page (Blank page,
+  Calendar, Cards, Chart, Comments, Content row, Dashboard, Data loading, Faceted search, Form, Interactive grid,
+  Interactive report, Map, Master detail, Media list, Report and form, Search page, Smart filters, Timeline, Tree,
+  Unified task list, Wizard, Workflow console) and **Create pages with AI**. A type that works on a table asks
+  for the table first; the others go to their options at once.
+- **Feature**: [features](#add-feature) to add to the application.
+- **Copy**: [a page of this or another application](#create-page-as-copy) under a new number.
+
+The wizards are plain forms (they work without JavaScript). Choose a
 **page type** and a **table or view** (tables the app's database role can't read are marked) and
-press **Next**. The second step proposes everything from the database catalog: the columns, the
+press **Next** (the App home's *Create pages from a table* form still does the same in one step). The second step proposes everything from the database catalog: the columns, the
 primary key, date and number columns, positions and foreign keys. Change what you like, choose the
 page number, name and menu icon, and press **Create page**: the builder opens the new page in the
 page designer. An error (a page number in use, a column that doesn't fit) shows on the second
@@ -886,6 +896,15 @@ step, which keeps the table and type.
 | **Map** | A [map](04-pages-and-regions.md#map) region with popups and, if ticked, an interactive report of the same rows that the map filters (*Show this area in the list*) | Position: a PostGIS geometry or geography (markers, and lines and areas as shapes), a `point`, `lat`/`lng`-like number columns, or a *location* text column with `latitude,longitude` |
 | **Faceted search** | An interactive report (9 columns wide) and a [facets](04-pages-and-regions.md#facets-faceted-search) panel (3 columns, collapsible) with a search field | Up to six facets: foreign keys (values of the parent's name, which the report shows instead of the key), booleans, text columns with few values, dates and numbers as ranges with *from*/*to* |
 | **Master detail** | One page with a grid of the table and an editable grid of the selected row's details below it (the grids' [master-detail](04-pages-and-regions.md#grid-interactive-grid)): a hidden item for the selection, both grids with a grid DML process; new detail rows get the master's key | The detail table: a table with a foreign key to this table's primary key |
+| **Interactive report** | (137) An [interactive report](04-pages-and-regions.md#report-interactive-report) of the table on a page of its own (parents' names next to foreign keys, labels and number formats), optionally with a modal form page | |
+| **Smart filters** | (137) An interactive report with a [smart filters](04-pages-and-regions.md#smart_filters) search field above it | The faceted search's facets |
+| **Tree** | (137) A [tree](04-pages-and-regions.md#tree) region: one node per row | Id: the primary key; parent: a foreign key to the table itself (`mgr` → `empno`); label: the name column |
+| **Timeline**, **Media list**, **Content row**, **Comments** | (137) A region of the [built-in template component](04-pages-and-regions.md#built-in-template-components) `ut_timeline`, `ut_media_list`, `ut_content_row` or `ut_comments`, all rows in one list | Title: the name column; when / date: a date or timestamp column (newest first); text: a comment-, body- or description-like column; who: a user- or author-like column, else the first foreign key |
+| **Data loading** | (137) A [data load definition](16-files.md#data-load-definitions) for the table (unless one of that name exists) and a page with a file item, **Load** and a `data_load` process | Mode *merge* for a table with a primary key, else *append* |
+| **Wizard** | (137) One page per step (APEX: Wizard), each with a [wizard progress](04-pages-and-regions.md#list-lists) list, the step's fields, Cancel, Previous and Next; **Finish** on the last step adds the row (an `INSERT` of every step's items as the app's role). The items keep their values in the session while the user goes back and forth | Every column but the key and generated ones, shared out over two to five steps |
+| **Search page** | (137) A [search region](04-pages-and-regions.md#search-search-region) over the application's search configurations you tick, and/or a new configuration on a table (its text columns searched, its name column as the title) | |
+| **Dashboard** | (137) A chart per table you tick (at most six), chosen from the data like a [new application's dashboard](#what-the-generated-pages-look-like) | |
+| **Unified task list**, **Workflow console** | (137) A [`tasks`](06-processing.md#approvals-and-the-task-list) region (my tasks, the ones I requested, or the ones I administer) or a [`workflows`](06-processing.md#workflows) region | |
 
 Cards, Calendar, Map and Faceted search take an optional **Form page** number: it adds a modal
 form page for a row, a link from each card, event, popup or report row, and a **Create** button
@@ -908,6 +927,41 @@ and **Create the ticked pages**. They are made with `meta.generate_page` and the
 in one transaction (all or none); only page types of the list and tables the application can read
 are accepted, whatever the form says.
 
+### Add feature
+
+(sprint 137; APEX: Create a Page → Feature, and App home → Tasks → Add Feature Page) **Create page → Feature**
+(or **Add feature page** under Tasks) lists features to add to an existing application. Each one first shows
+what it adds, and adds it only when you press its button; once installed it is greyed out and can't be added
+twice (also when two developers press at the same moment).
+
+| Feature | What it adds |
+|---|---|
+| Access control | Authorization schemes `CONTRIBUTOR` and `READER` (and `ADMIN` when missing) for the roles admin, contributor and reader |
+| Activity reporting | Page 9010 *Activity* for administrators (authorization `ADMIN`): page views per day and the latest activity, from `meta.app_activity()`, and its navigation entry |
+| Configuration options | Page 9020 *Configuration* for administrators: the [configurable build options](06-processing.md#build-options) as switches, and Save; you tick which build options are configurable |
+| E-mail reporting | The application setting `EMAIL_REPORT_TO` and the automation `EMAIL_REPORTING`: every Monday at 07:00 UTC the [activity report by mail](06-processing.md#the-activity-report-by-mail) |
+| Feedback | [Feedback](#feedback) from the header |
+| About page | Page 9000 *About* in a Help menu of the navigation bar |
+| Login page | An editable [login page](08-security.md#the-login-page) (page 9999, or the next free number); not offered without sign-in |
+| Theme style selection | Users choose light or dark (Appearance in the user menu) |
+| Push notifications | Install as an app and push notifications, with the application's key pair; needs `PGKILN_SECRET_KEY` |
+
+A page number in use by another page blocks the feature that needs it (it says so).
+
+### Create page as copy
+
+(sprint 137; APEX: Create Page as Copy) **Create page → Copy** copies a page of this application or of another
+application of the same workspace: choose the application, then the page, then the new page number and name.
+Everything on the page comes along (regions, items, buttons, dynamic actions, validations, processes,
+computations and branches); items named `P20_…` are renamed to the new number, also where the page's SQL, links
+and conditions refer to them, and links to the page itself point to the copy.
+
+The page's **shared components** (lists of values, authorization schemes, build options, lists, template
+components, search configurations, data load definitions) are listed: for each, use one of this application's
+(the one with the same name is chosen when there is one), or, from another application, **copy it** along. The
+page's SQL runs as this application's database role afterwards: grant it what the other application's role
+could read. From SQL: `meta.copy_page(from_app, page, to_app, new_page, name, map)`.
+
 ### Create a blank page
 
 Give a page number, name, mode (normal or modal dialog) and breadcrumb parent, then add
@@ -1526,6 +1580,55 @@ Database code (views, functions, RLS policies) isn't part of the application, so
 
 Findings are errors, warnings or notes, each linking to the component.
 
+## Utilities
+
+**Utilities** (the last tab of an application, APEX: Application Utilities) gathers what an
+application's upkeep needs: tiles for the Advisor, Search, Debug messages, Activity, Backups,
+Working copies and Export, and the tools below. It also shows an **application dashboard** (pages,
+regions, items, processes, lists of values, changes in the last 7 days), the **recently updated
+pages** (from the change history) and the checksums.
+
+- **Database object dependencies** (`/builder/apps/:id/utilities/dependencies`): every piece of SQL
+  the Advisor plans, plus the tables of form and grid regions, is parsed as the application's
+  database role into a temporary SQL-standard function (`CREATE FUNCTION … BEGIN ATOMIC`, rolled
+  back, nothing runs), and PostgreSQL's own dependency records name the tables, views, sequences
+  and functions it uses, resolved with the role's search path. Each object links to the Object
+  Browser and lists the components (and pages) that use it. An object that doesn't exist (a dropped
+  view, say `sales.orders_v`) is marked **Missing** in red, and so is a privilege the role lacks
+  (**No grant**: SELECT for queries, INSERT / UPDATE / DELETE on the target of a DML statement,
+  USAGE on sequences, EXECUTE on functions, USAGE on the schema). PL/pgSQL blocks and statements
+  other than SELECT, INSERT, UPDATE, DELETE and MERGE are listed as not scanned.
+- **Change history** (`/builder/apps/:id/utilities/history`): after every change made in the
+  builder, and inside every import `--replace` (restoring a backup, merging a working copy, the
+  command line and the MCP server), the application's export is compared with the one after its
+  previous change, component by component as working copies compare (a page's settings, a region
+  with its SQL, an item, a list of values, …). Each added, changed or deleted component is kept with
+  who (the developer; none for the command line), when and its files before and after; **Show**
+  gives the differences as a diff. Filter by developer, date range, page and component name.
+  History is kept `CHANGE_HISTORY_DAYS` days (365 by default; 0 keeps everything) and starts with
+  the first change after the upgrade to the version that introduced it.
+- **Upgrade application** (`/builder/apps/:id/utilities/upgrade`): components made before pgkiln
+  gained a better default, each with the reason, a **Preview** of the change and **Upgrade** (or
+  *Upgrade all* of a kind): an application without a navigation appearance (→ Pillar Light), a text
+  item of a form on a `date` or `timestamp` column (→ a date or date-time item with the date
+  picker), a select list whose list of values reads a table of more than 1,000 rows (→ a popup list
+  of values, searched and paged on the server). Upgrades are recorded in the change history.
+- **UI defaults** (`/builder/ui-defaults`, also under Workspace utilities; APEX: Attribute
+  Dictionary): per table column a label, format mask, help text, alignment and list of values
+  (`LOV:NAME`, `STATIC:…` or a query). The page wizards and the Create Application wizard use the
+  label for report headings and form items, and a form item a wizard makes also gets the column's
+  format mask, help and list of values. **Seed from comments** fills the columns without a UI
+  default from their `COMMENT ON`: a short comment (60 characters at most) becomes the label, a
+  longer one the help. UI defaults belong to the installation (not exported with an application)
+  and apply to pages generated after the change. The tables offered are those the workspace's SQL
+  Workshop can see.
+- **Application checksum**: a SHA-256 of the application's definition (its export in the text
+  layout, without the alias), with a checksum per page: the same definition gives the same checksum
+  on any installation, so two installations, or an application and its working copy, compare at a
+  glance. Export sends it too, in the `X-Pgkiln-Checksum` response header.
+- **Icons** (`/builder/icons`): the icon picker's set, pgkiln's own icons and the Lucide icons by
+  search, with the names to use in icon fields.
+
 ## Activity monitor
 
 Per application: page views, distinct users and average page time over the last 24 hours;
@@ -1621,6 +1724,15 @@ doesn't allow:
   `PGKILN_REST_PRIVATE_HOSTS` lists it). The server resolves the host once and connects to the address it checked,
   with the host name kept for TLS, on every send and test.
 
+### OpenTelemetry
+
+Workspace utilities → **OpenTelemetry** (`/builder/telemetry`, administrators; APEX 24.2: Workspace Utilities →
+OpenTelemetry): traces, logs and metrics of the applications to an OpenTelemetry Collector, and `GET /metrics` for
+Prometheus. A workspace's page → *Mail and network access* → **OpenTelemetry** lets its administrators switch its
+applications off or send them to a collector of their own as well (through the allow-list and the workspace's
+[network access](#network-access) list). What is sent, the values left out and the settings are in
+[chapter 1](01-installation.md#monitoring-with-opentelemetry).
+
 ### Network access
 
 Administration menu → **Network access** (`/builder/network`; APEX 26.2: workspace network ACLs), for administrators

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

@@ -1160,7 +1160,8 @@ select empno as id, mgr as parent_id, initcap(ename) || ' · ' || initcap(job) a
 ```
 
 Attributes: `expanded` (levels open at first, default 1), `link` (as for maps; `#id#` and any other
-column), `empty`. The tree is drawn on the server with `<details>`: it works without JavaScript,
+column), `empty`. (137) **Create page → Tree** makes one from a table: the key as the id, a foreign key to the
+table itself (`mgr` → `empno`) as the parent and the name column as the label. The tree is drawn on the server with `<details>`: it works without JavaScript,
 and the browser's find-in-page opens closed branches. Clicking a label follows the link; the rest
 of the row opens and closes the branch. Up to 5000 nodes.
 
@@ -1460,6 +1461,7 @@ with 26.1's *Metric Card* and group support). Show a region as `multiple` to get
 | `ut_avatar` | Avatar: a picture or initials | `NAME`, `INITIALS`, `IMAGE` (a relative or https URL), `SIZE` (small, medium, large), `SHAPE` (circle, square) | An avatar group (overlapping) |
 | `ut_badge` | Badge coloured by a state | `LABEL`, `STATE` (success, warning, danger, info, neutral; approved, pending, … are understood) | A row of badges |
 | `ut_comments` | Comments | `USER`, `INITIALS`, `DATE`, `COMMENT`, `ACTIONS` (extra text) | One conversation |
+| `ut_content_row` | (137) Content row: initials or a picture, title (linked when the region has a link) and description, a secondary text and a badge on the right | `TITLE`, `DESCRIPTION`, `MISC`, `INITIALS`, `IMAGE`, `BADGE`, `STATE` | One list |
 | `ut_media_list` | Media list: picture or initials, title (linked when the region has a link), description, badge | `TITLE`, `DESCRIPTION`, `INITIALS`, `IMAGE`, `BADGE`, `STATE` | One list |
 | `ut_metric_card` | Metric card: a key figure with its unit, change and trend | `LABEL`, `VALUE`, `UNIT`, `CHANGE`, `TREND` (up, down, flat), `GOOD` (up or down: which direction shows green), `DESCRIPTION` | A row of cards |
 | `ut_timeline` | Timeline: when, who, title, text, a coloured marker | `TITLE`, `WHEN`, `WHO`, `BODY`, `STATE` | One timeline |

package/docs/guide/05-items.md

@@ -21,7 +21,7 @@ page, optionally inside a region. Name them `P<page>_<NAME>` (uppercase letters,
 | `radio` | radio group | the chosen return value |
 | `checkbox` | a single checkbox | `true` / `false` |
 | `switch` | on/off switch | `true` / `false` |
-| `checkbox_group` | several checkboxes | **colon-separated** return values, e.g. `10:30` |
+| `checkbox_group` | several checkboxes | **colon-separated** return values, e.g. `10:30`; (137) `{"switches": true}` shows each as a switch, one per line |
 | `multiselect` | multi-select list | **colon-separated** return values |
 | `display` | read-only text (shows the display value for list items) | whatever was set |
 | `hidden` | not rendered | set by URL (with checksum), fetch or processes |

package/docs/guide/06-processing.md

@@ -598,6 +598,15 @@ the component out (fail closed); the Advisor reports it. Build options are part
 export. On HR page 22, the *Forecast* region needs `LEAVE_FORECAST` (excluded), and *Planner tips*
 (`!LEAVE_FORECAST`) takes its place until it is included.
 
+**Configurable build options** (sprint 137; APEX: the Configuration Options feature): tick *Configurable* on a
+build option, and **Create page → Feature → Configuration options** adds page 9020 *Configuration* where the
+application's administrators switch those options on and off while it runs (a checkbox group shown as switches,
+`{"switches": true}`). From SQL, as the application's own role and for a user with the `admin` role only:
+`meta.configurable_options()` (name, description, enabled) and `meta.set_configurable_options('EXPORT:BETA')`
+(the named ones included, the other configurable ones excluded; an option that is not configurable is refused).
+The change applies to every user at once, like a change in the builder. An import of a newer version of the
+application sets the options as the export has them.
+
 ## Application processes
 
 **Shared Components → Application processes** run for the whole application:
@@ -819,6 +828,15 @@ work for the **current application** only when the caller runs as that applicati
 (pages, processes, automations, workflows and background chains do); the SQL Workshop is not an
 application.
 
+### The activity report by mail
+
+`meta.send_activity_report(to, days default 7)` (sprint 137; APEX: the Email Reporting feature) queues a mail with
+the current application's activity of the last days (page views, users, sign-ins, failed sign-ins, errors and the
+most viewed pages) and the rows as `activity.csv`. It is for the application's automations and its signed-in
+administrators; others get an error. **Create page → Feature → E-mail reporting** adds the application setting
+`EMAIL_REPORT_TO` and an automation `EMAIL_REPORTING` that sends it every Monday at 07:00 UTC; without addresses
+nothing is sent.
+
 ### E-mail templates
 
 Shared Components → **E-mail templates** (APEX: Email Templates): a name, a subject, an HTML body

package/docs/guide/09-reference.md

@@ -296,13 +296,16 @@ Run these as the owner (in the SQL Workshop, `psql` or migrations):
 |---|---|
 | `meta.generate_crud(app, table, report_page, form_page, label default null, icon default 'table')` | Report page + modal form page + menu entry for a table, with the column names as labels (kept as it was for existing scripts; `meta.generate_page` *report_form* makes the labelled pages of the wizards) |
 | `meta.generate_grid(app, table, page, label default null, icon default 'grid')` | Interactive grid page + menu entry |
-| `meta.generate_page(app, kind, table, page, options default '{}')` | The create page wizards: `kind` is `form`, `cards`, `calendar`, `chart`, `map`, `facets`, `master_detail` (or `report_form`, `grid`). Options left out take the defaults of `meta.wizard_defaults`; JSON `null` means none. Returns the new page's id (below) |
+| `meta.generate_page(app, kind, table, page, options default '{}')` | The create page wizards: `kind` is `form`, `cards`, `calendar`, `chart`, `map`, `facets`, `master_detail` (or `report_form`, `grid`); (137) also `report`, `smart_filters`, `tree`, `timeline`, `media_list`, `content_row`, `comments`, `data_load`, `wizard`, and without a table (`null`) `search`, `tasks`, `workflows`. Options left out take the defaults of `meta.wizard_defaults`; JSON `null` means none. Returns the new page's id (below; a wizard: its first page's) |
 | `meta.wizard_defaults(kind, table)` | The options a wizard proposes for a table, from the catalog |
 | `meta.wizard_catalog(table)` | The columns as the wizards see them: kind (`text`, `number`, `date`, `timestamp`, `boolean`, `point`, `geometry`, `binary`, `other`), key, unique, foreign key and the parent's display column |
 | `meta.wizard_label(name)`, `meta.wizard_table_label(table, plural default true)`, `meta.wizard_column_label(table, column)` | (097) The labels of the wizards: `hiredate` → *Hire Date*, `hr.emp` → *Employees* / *Employee*, `deptno` → *Department*; short comments win ([what the generated pages look like](03-builder.md#what-the-generated-pages-look-like)) |
 | `meta.wizard_report(table, columns default null)` | (097) A report on a table as the wizards make it: `{"source", "hidden", "headings", "formats"}` (foreign keys joined to their parent's display column) |
 | `meta.wizard_grid_labels(table)` | (100) An interactive grid's `{"headings", "formats"}` as the wizards make them: the labels of `meta.wizard_column_label` and the number format masks (keys get none) |
 | `meta.app_activity(days default 30)` | (098) The current application's page views, sign-ins and errors of the last days (1 to 366, at most 10,000 rows, no IP addresses), for a signed-in user with the `admin` role of that application; others get an error. The Activity page of the Create Application wizard reads it |
+| `meta.configurable_options()`, `meta.set_configurable_options(names)` | (137) The current application's [configurable build options](06-processing.md#build-options) (name, description, enabled), and switching them (`names` colon-separated: those are included, the other configurable ones excluded). Only as the application's own role, for a user with the `admin` role; other options are refused |
+| `meta.send_activity_report(to, days default 7)` | (137) Queue a mail with a summary of the current application's activity of the last days and the rows as `activity.csv`. For the application's automations and its signed-in administrators; empty `to`: nothing is sent. The *E-mail reporting* feature's automation calls it |
+| `meta.copy_page(from_app, page, to_app, new_page, name default null, map default '{}')` | (137) [Create page as copy](03-builder.md#create-page-as-copy) (owner only); `map` is `{"lov:JOBS": "JOB_TITLES"}`: a shared component to use instead of copying it. `meta.page_shared_refs(page_id, target_app)` lists what a page refers to by name |
 | `meta.wizard_files(table)` | (097) The `bytea` columns and the columns holding their file name, mime type, size and change time |
 | `meta.export_app(alias)` | The application as JSON (`pgkiln/2` format) |
 | `meta.import_app(json, alias default null)` | Import an export, optionally under a new alias; returns the new app id |
@@ -327,6 +330,17 @@ Options of `meta.generate_page` (all optional; column names must be columns of t
 | `facets` | `columns` (report columns, array), `facets` (array), `search` (boolean), `form_page` |
 | `master_detail` | `detail` (a table), `detail_column` (its column referring to this table) |
 | `report_form` | `form_page` (required) |
+| `report` | `form_page` (137: an interactive report alone) |
+| `smart_filters` | `facets` (array), `form_page` |
+| `tree` | `id_column`, `parent_column` (proposed: a foreign key to the table itself), `label_column`, `expanded` (levels open), `form_page` |
+| `timeline` | `title`, `when`, `who`, `body`, `form_page` |
+| `media_list`, `content_row` | `title`, `description`, `badge` (also its colour), `misc` (content row), `form_page` |
+| `comments` | `user`, `date`, `comment` |
+| `data_load` | `definition` (a data load definition's name: made for the table unless it exists), `mode` (`append`, `merge`, `replace`), `skip_errors` |
+| `wizard` | `columns` (array; NOT NULL columns without a default always), `steps` (1–10), `return_page` |
+| `search` | `configs` (search configurations by name); with a table: a new configuration on it, and `form_page` |
+| `tasks` | `context` (`my`, `initiated`, `admin`), `completed` (boolean) |
+| `workflows` | `context` (`initiator`, `admin`) |
 
 ```sql
 select meta.generate_page('shop', 'calendar', 'shop.meeting', 12, '{"form_page": 13, "drag": true}');
@@ -635,6 +649,9 @@ pgkiln's icons; its filter box also searches the Lucide icons by name and search
 | `GET/POST /a/:alias/account`, `POST /a/:alias/account/password`, `POST /a/:alias/account/theme`, `POST /a/:alias/account/style` | My account, own password, the light/dark switch, the [style variant](14-globalization.md#style-variants-theme-roller) switch |
 | `POST /a/:alias/tz` | The browser's time zone for the session (automatic time zone; sent by `app.js`, CSRF token required) |
 | any page `?lang=xx` | Switch the language for the session |
+| `POST /a/:alias/telemetry` | (0.72) Browser spans of a page whose trace goes to an OpenTelemetry collector (sent by `app.js`; a signed token of the page, 204) |
+| `GET /metrics` | (0.72) Metrics in the Prometheus text format, when switched on: an administrator's builder session or `Authorization: Bearer <metrics token>` ([chapter 1](01-installation.md#monitoring-with-opentelemetry)) |
+| `GET /healthz` | `ok` when the database is reachable (503 otherwise) |
 | `/builder/...` | Builder |
 | PostgREST (separate service, `API_URL`) | REST API of each app's `api` schema, see [chapter 13](13-rest-api.md) |
 | `/static/...` | CSS, JavaScript, icons |

package/docs/guide/12-development.md

@@ -190,6 +190,21 @@ src/
   debug.ts                 debug messages: DebugLog (levels, timed steps, NOTICEs of meta.debug from appTx), started in
                            loadContext, stored after the response (onResponse hook → meta.debug_save), hourly purge
   icons.ts                 icon helper (sprite in public/icons.svg)
+  telemetry/               (sprint 139, AP-6) OpenTelemetry without the SDK: trace.ts (the current trace in AsyncLocalStorage,
+                           startTrace/endTrace, withSpan/rootSpan/recordSpan, traceApp, traceparent, a span per statement by
+                           patching pg.Client#query, sanitizeSql/redactText, counters and histograms), config.ts (the instance's
+                           settings: meta.setting otel_* over OTEL_* variables; workspaces' telemetry columns; app → workspace,
+                           cached 30 s), export.ts (a queue per collector, OTLP/HTTP JSON for traces, logs and metrics, values
+                           only where included, gauges from the queues, prometheusText(), sendTest()), http.ts (a trace per
+                           request, request metrics, GET /metrics, POST /a/:alias/telemetry), browser.ts (the page's signed
+                           <meta name="pgkiln-trace"> in layout.ts and relay() of what app.js reports). Spans come from
+                           webclient.ts (outgoing calls, traceparent), ai/service.ts logUsage, runtime/ai-agents.ts logToolCall,
+                           mail/mail.ts sendOne, workflow.ts runWorkflow; logs from session.ts logActivity
+  history.ts               (sprint 138, AP-5) change history and checksums: meta.app_snapshot (the export after the last recorded
+                           change), recordHistory() (export again, workingcopy.ts components() of both, each added/changed/deleted
+                           component with its files before and after into meta.component_change; called by app-updates.ts onSend,
+                           the upgrade page and cli/replace.ts replaceApp), ensureSnapshot() (before a first change), diffDocs(),
+                           appChecksum() / pageChecksums() (SHA-256 of the text layout without the alias), CHANGE_HISTORY_DAYS
   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
@@ -245,7 +260,7 @@ src/
     tree.ts                tree region
     lists.ts               lists: static entries or a query, visibility (authorization, conditions, page access), safe URLs; list regions, navigation menu and bar
     template-components.ts template components: template language (allow-list, directives, escaping), plug-in files, report column templates
-    builtin-components.ts  built-in template components (ut_avatar, ut_badge, ut_comments, ut_media_list, ut_metric_card, ut_timeline)
+    builtin-components.ts  built-in template components (ut_avatar, ut_badge, ut_comments, ut_content_row, ut_media_list, ut_metric_card, ut_timeline)
     template-region.ts     template_component region
     tasks.ts               task list region and task actions (approvals); (094) the vacation rule panel and route;
                            (sprint 114) custom outcome buttons, the Fail event and recovery of a failing completion SQL
@@ -309,6 +324,10 @@ src/
                            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
+    create-page.ts         (137) Create page: the grid of page types with SVG previews (tabs Component / Feature / Copy), the table step,
+                           Create page as copy (step per app and page, shared components mapped or copied → meta.copy_page)
+    features.ts            (137) Add feature: review (what it adds) and install, once, of Access control, Activity reporting,
+                           Configuration options, E-mail reporting, Feedback, About, Login page, Theme style selection, Push
                            (the generators are PL/pgSQL in migration 047: catalog, defaults, form/cards/calendar/chart/map/facets/master-detail)
     home.ts                App Builder home at /builder/apps and /builder (tiles, applications report/cards, Recent; /builder redirects
                            to the Workspace home when meta.workspace.builder_home = 'home'), Create, Import, Dashboard, Utilities;
@@ -383,6 +402,9 @@ src/
     vector-providers.ts    (sprint 136, AP-1) Shared Components → Vector providers (/apps/:id/vector-providers: list, provider form,
                            test, delete) and Workspace utilities → Vector providers (/vector-providers: pgvector status, Create
                            extension for administrators, the workspace's providers and vector columns); pgvectorNote()
+    telemetry.ts           (sprint 139, AP-6) Workspace utilities → OpenTelemetry (/telemetry: the collector, signals, values, user,
+                           browser spans, /metrics and its token, status per collector, Send a test span; administrators) and a
+                           workspace's own (/workspaces/:id/telemetry: as the instance / off / own collector; its administrators)
     data-security.ts       (sprint 119) a table's Security: GET/POST /sql/objects/security?o= (policies, roles × columns, masks), Preview / Apply
     object-actions.ts      (sprint 94) an object's ⋯ menu (objectMenu) in the worksheet and the Object Browser: Quick DDL (objectDdl), Drop with
                            dependents, Add index / trigger / policy as drafts; GET /sql/objects/action, /sql/objects/panel (Open in a panel)
@@ -412,6 +434,18 @@ 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
+    utilities.ts           (sprint 138, AP-5) an application's Utilities tab: tiles, dashboard figures, recently updated pages,
+                           application and page checksums; Change history (filters, diffHtml of a change); the icon browser
+                           /builder/icons; historyHooks() (preHandler: ensureSnapshot before a builder POST of an application)
+    dependencies.ts        (sprint 138) Utilities → Database object dependencies: appDependencies() (the Advisor's fragments, each
+                           parsed as the app role into a BEGIN ATOMIC temp function, one statement by the extended protocol;
+                           pg_depend → tables, views, sequences, functions; missing objects from the parser's errors; privileges
+                           needed vs the role's), the page with Object Browser links
+    upgrade.ts             (sprint 138) Utilities → Upgrade application: upgradeCandidates() (nav_appearance, date_picker,
+                           popup_lov), preview diff, POST upgrade by key or rule (found again first), recorded in the history
+    ui-defaults.ts         (sprint 138) UI defaults /builder/ui-defaults (meta.ui_default, migration 138): per column label, mask,
+                           help, alignment, list of values; seed from comments; tables of the workspace's catalog only. The wizards
+                           read them through meta.wizard_column_label and the meta.item trigger meta.ui_default_item
     ddl-tools.ts           SQL Workshop → DDL and Compare (src/ddl.ts); (sprint 106) the Apply and record form
     changelog.ts           (sprint 106) SQL Workshop → Change Log (/builder/sql/changes): change sets per schema, latest app export,
                            downloads (POST, mark exported_at), rename, delete; /sql/compare/apply (one transaction, recorded)

package/docs/guide/16-files.md

@@ -406,7 +406,7 @@ The HR sample has `EMP_XML`, for XML files like `/static/samples/employees.xml`.
 ### Data loading in an application
 
 For end users, add a page with a `file` item and a button, and a **process of type
-`data_load`**. The process runs **as the application's database role**, so grants, row level
+`data_load`** ((sprint 137) **Create page → Data loading** makes the definition and such a page for a table). The process runs **as the application's database role**, so grants, row level
 security, triggers and the audit trail apply, just as they do for the form.
 
 | `config` key | Meaning |

package/examples/hr/hr_73_configuration_options.sql

@@ -0,0 +1,17 @@
+-- =====================================================================
+-- HR example, part 73: a configurable build option (sprint 137, AP-3;
+-- migration 137; docs/guide/06-processing.md "Build options",
+-- 03-builder.md "Add feature")
+--
+-- LEAVE_FORECAST (part 22: the Forecast region of page 22, excluded) is
+-- marked configurable. In the builder, Create page → Feature →
+-- Configuration options then adds page 9020 "Configuration" where HR's
+-- administrators (king, demo) switch the forecast on and off while the
+-- application runs, without a developer. Nothing else changes until that
+-- feature is added.
+-- =====================================================================
+
+update meta.build_option o set configurable = true,
+       description = coalesce(o.description, 'The leave forecast on the leave planner (page 22)')
+  from meta.app a
+ where a.id = o.app_id and a.alias = 'hr' and o.name = 'LEAVE_FORECAST';

package/examples/hr/hr_74_app_utilities.sql

@@ -0,0 +1,22 @@
+-- =====================================================================
+-- HR example, part 74: an application's Utilities (sprint 138, AP-5;
+-- migration 138; docs/guide/03-builder.md "Utilities")
+--
+-- UI defaults (App Builder → Utilities → UI defaults, or Workspace
+-- utilities → UI defaults) for hr.leave_request: the page wizards and the
+-- Create Application wizard label its "days" column "Working days" and
+-- show it with a number format mask, and a generated form item for
+-- "reason" gets a help text. Pages that exist already don't change: create
+-- a form on hr.leave_request (Create Page → Form) to see them.
+--
+-- The rest of the Utilities page needs no example data: Database object
+-- dependencies, Change history (recorded from the next change on),
+-- Upgrade application and the application checksum work on the HR
+-- application as it is.
+-- =====================================================================
+
+insert into meta.ui_default (schema_name, table_name, column_name, label, format_mask, help, alignment, updated_by)
+values
+  ('hr', 'leave_request', 'days', 'Working days', '990', 'Working days the leave takes, without weekends and public holidays.', 'end', 'admin'),
+  ('hr', 'leave_request', 'reason', null, null, 'Optional: what the leave is for. Your manager sees it when deciding.', null, 'admin')
+on conflict (schema_name, table_name, column_name) do nothing;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgkiln",
-  "version": "0.70.0",
+  "version": "0.72.0",
   "description": "Open source low-code, SQL-driven application builder for PostgreSQL, inspired by Oracle APEX",
   "keywords": [
     "postgresql",

package/public/app.css

@@ -1602,6 +1602,15 @@ img.tc-avatar { object-fit: cover; }
 .tc-media { display: flex; gap: 0.8rem; align-items: center; padding: 0.6rem 0; min-width: 0; overflow-wrap: anywhere; }
 .tc-media > .tc-stack { flex: 1; }
 .tc-media-badge { flex: none; }
+/* (137) ut_content_row: avatar, title and description, secondary text and badge on the right */
+.tc-content-rows { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; }
+.tc-content-row { display: flex; gap: 0.8rem; align-items: center; padding: 0.6rem 0; min-width: 0; overflow-wrap: anywhere; }
+.tc-content-row + .tc-content-row { border-top: 1px solid var(--border); }
+.tc-content-row > .tc-stack { flex: 1; }
+.tc-content-row-end { display: flex; flex-direction: column; align-items: flex-end; gap: 0.25rem; flex: none; max-width: 40%; text-align: end; }
+@media (max-width: 480px) { .tc-content-row { flex-wrap: wrap; } .tc-content-row-end { flex-direction: row; align-items: center; max-width: none; margin-inline-start: auto; } }
+/* (137) a checkbox group shown as switches ({"switches": true}): one per line */
+.radio-group.switch-group { flex-direction: column; align-items: flex-start; }
 .tc-metrics { display: grid; grid-template-columns: repeat(auto-fill, minmax(min(100%, 13rem), 1fr)); gap: 0.75rem; }
 .tc-metric { gap: 0.25rem; }
 .tc-metric-label { margin: 0; color: var(--muted); font-size: 0.85rem; font-weight: 600; }

package/public/app.js

@@ -4362,3 +4362,53 @@ document.addEventListener('change', (e) => {
     });
   }
 })();
+
+// (sprint 139, AP-6) Browser spans: a page whose trace goes to an OpenTelemetry collector carries a
+// signed <meta name="pgkiln-trace">. Its load timings and its Ajax calls to the same application are
+// reported to pgkiln (POST /a/<alias>/telemetry), which adds them to the page's trace; the browser
+// never sees the collector. Nothing happens on pages without the meta.
+(() => {
+  const meta = document.querySelector('meta[name="pgkiln-trace"]');
+  const m = /^\/a\/[^/]+\//.exec(location.pathname);
+  if (!meta || !m || !window.fetch || !window.performance) return;
+  const token = meta.content;
+  const url = `${m[0]}telemetry`;
+  const origin = performance.timeOrigin || Date.now() - performance.now();
+  let queue = [];
+  const send = () => {
+    if (!queue.length) return;
+    const body = JSON.stringify({ t: token, spans: queue.splice(0, 50) });
+    const blob = new Blob([body], { type: 'application/json' });
+    if (!(navigator.sendBeacon && navigator.sendBeacon(url, blob)))
+      realFetch(url, { method: 'POST', body, headers: { 'content-type': 'application/json' }, keepalive: true, credentials: 'same-origin' }).catch(() => {});
+  };
+  const realFetch = window.fetch.bind(window);
+  window.fetch = function (input, init) {
+    const t0 = performance.now();
+    let path = '';
+    try {
+      const u = new URL(typeof input === 'string' ? input : input instanceof Request ? input.url : String(input), location.href);
+      if (u.origin === location.origin && u.pathname.startsWith(m[0]) && u.pathname !== url) path = u.pathname + u.search;
+    } catch {
+      // not a URL we report
+    }
+    const p = realFetch(input, init);
+    if (path) {
+      const method = String((init && init.method) || (input instanceof Request ? input.method : 'GET')).toUpperCase();
+      const done = (status) => {
+        queue.push({ k: 'ajax', path, method, status, start: origin + t0, dur: performance.now() - t0 });
+        if (queue.length >= 20) send();
+      };
+      p.then((r) => done(r.status), () => done(0));
+    }
+    return p;
+  };
+  window.addEventListener('load', () => setTimeout(() => {
+    const n = performance.getEntriesByType('navigation')[0];
+    if (n) queue.push({ k: 'load', start: origin + n.startTime, dur: (n.loadEventEnd || performance.now()) - n.startTime,
+      t: { ttfb: n.responseStart - n.startTime, dom_interactive: n.domInteractive - n.startTime, dom_complete: n.domComplete - n.startTime, load: n.loadEventEnd - n.startTime } });
+    send();
+  }, 0));
+  document.addEventListener('visibilitychange', () => { if (document.visibilityState === 'hidden') send(); });
+  window.addEventListener('pagehide', send);
+})();

package/public/builder.css

@@ -1600,3 +1600,51 @@ pre.wrap-pre { white-space: pre-wrap; overflow-wrap: anywhere; }
 
 /* (sprint 136) a button inside an alert (e.g. Add vector column without pgvector) wraps on a phone instead of overflowing */
 .alert .btn { white-space: normal; overflow-wrap: anywhere; max-width: 100%; }
+
+/* (sprint 137, AP-3) Create page: the grid of page types with small previews, the features, the type's step */
+.cp-tabs { margin-bottom: 0.9rem; flex-wrap: wrap; }
+.cp-grid { list-style: none; margin: 0; padding: 0; display: grid; grid-template-columns: repeat(auto-fill, minmax(10.5rem, 1fr)); gap: 0.75rem; }
+.cp-grid > li { min-width: 0; }
+.cp-type { display: flex; flex-direction: column; gap: 0.35rem; height: 100%; padding: 0.6rem; border: 1px solid var(--border); border-radius: var(--radius); background: var(--surface); color: var(--text); text-decoration: none; overflow-wrap: anywhere; }
+a.cp-type:hover, a.cp-type:focus-visible { border-color: var(--accent); }
+.cp-type b { font-size: 0.95rem; }
+.cp-type small { color: var(--muted); line-height: 1.35; }
+.cp-type .tag { align-self: flex-start; }
+.cp-done { opacity: 0.6; }
+.cp-preview { display: block; border-radius: var(--radius-sm); background: var(--surface-2); padding: 4px; }
+.cp-preview-lg { max-width: 16rem; }
+.cp-svg { display: block; width: 100%; height: auto; }
+.cp-svg .pv-line { fill: var(--border-strong); }
+.cp-svg .pv-soft { fill: color-mix(in srgb, var(--accent) 28%, var(--surface)); }
+.cp-svg .pv-acc { fill: var(--accent); }
+.cp-svg .pv-bg { fill: var(--surface); }
+.cp-svg .pv-frame { fill: var(--surface); stroke: var(--border-strong); stroke-width: 1; }
+.cp-svg .pv-stroke { fill: none; stroke: var(--border-strong); stroke-width: 1.5; }
+.cp-feature-icon { display: inline-flex; align-items: center; justify-content: center; width: 40px; height: 40px; border-radius: 10px; background: var(--accent-soft, var(--surface-2)); color: var(--accent); }
+.cp-step { display: flex; flex-wrap: wrap; gap: 1rem; align-items: flex-start; margin-bottom: 0.75rem; }
+.cp-step > .cp-preview { flex: 0 1 12rem; }
+.cp-step > p { flex: 1 1 14rem; margin: 0; }
+.cp-adds { padding-inline-start: 1.2rem; overflow-wrap: anywhere; }
+
+/* (sprint 138, AP-5) an application's Utilities: filters, the dashboard figures, object dependencies, icons, UI defaults */
+.util-filters { display: flex; flex-wrap: wrap; align-items: flex-end; gap: 0.5rem 0.75rem; margin-bottom: 0.75rem; }
+.util-filters .field { margin: 0; min-width: 0; flex: 1 1 9rem; }
+.util-filters .buttons { margin: 0; }
+.util-stats { display: grid; grid-template-columns: repeat(auto-fit, minmax(8rem, 1fr)); gap: 0.75rem; margin: 0; }
+.util-stats div { border: 1px solid var(--border); border-radius: var(--radius-sm, 6px); padding: 0.5rem 0.75rem; }
+.util-stats dt { color: var(--muted); font-size: 0.8rem; }
+.util-stats dd { margin: 0; font-size: 1.4rem; font-weight: 650; }
+.util-sum code, .util-history td, .dep-table td { overflow-wrap: anywhere; }
+.util-sum code { word-break: break-all; }
+.tag-success { background: var(--success-soft); color: var(--success); }
+.dep-problem td:first-child, .dep-missing { color: var(--danger); }
+.dep-list { margin: 0.25rem 0 0; padding-left: 1rem; }
+.dep-list a { display: inline-flex; gap: 0.3rem; align-items: center; }
+.util-icons { display: grid; grid-template-columns: repeat(auto-fill, minmax(6.5rem, 1fr)); gap: 0.5rem; margin: 0 0 1rem; padding: 0; list-style: none; }
+.util-icons .icon-tile { display: flex; flex-direction: column; align-items: center; gap: 0.35rem; padding: 0.6rem 0.25rem; border: 1px solid var(--border); border-radius: var(--radius-sm, 6px); text-align: center; }
+.util-icons code { font-size: 0.75rem; overflow-wrap: anywhere; }
+.ui-defaults :is(input, select, textarea) { width: 100%; min-width: 7rem; }
+.util-upgrade + .util-upgrade { margin-top: 1rem; }
+
+/* (sprint 139, AP-6) OpenTelemetry */
+.otel-problem { color: var(--danger); overflow-wrap: anywhere; }

package/src/ai/service.ts

@@ -3,6 +3,7 @@ import { decryptSecret } from '../secrets.ts';
 import { ClaudeProvider } from './anthropic.ts';
 import { OpenAiProvider } from './openai.ts';
 import { AiError, type AiProvider, type GenerateRequest, type GenerateResult, type ProviderName } from './types.ts';
+import { count, recordSpan } from '../telemetry/trace.ts';
 
 // AI services (migration 060; Gemini and OpenAI-compatible endpoints: 121): an administrator configures them in the
 // builder (Workspace utilities → AI services) and allows each application
@@ -115,6 +116,19 @@ export interface Usage {
 }
 
 export async function logUsage(info: Pick<CallInfo, 'appId' | 'pageNo' | 'user' | 'source'>, u: Usage) {
+  // (sprint 139, AP-6) the call as a span of the current trace (timed by the caller), tokens as metrics
+  if (u.status !== 'limited')
+    recordSpan(`AI ${u.service.provider} ${u.model}`.slice(0, 120), {
+      ms: u.ms,
+      attrs: {
+        'gen_ai.system': u.service.provider, 'gen_ai.request.model': u.model, 'gen_ai.operation.name': info.source === 'embedding' ? 'embeddings' : 'chat',
+        'gen_ai.usage.input_tokens': u.inputTokens, 'gen_ai.usage.output_tokens': u.outputTokens, 'pgkiln.ai.service': u.service.name, 'pgkiln.ai.source': info.source,
+      },
+      error: u.status === 'ok' ? null : `${u.status}${u.message ? `: ${u.message}` : ''}`,
+    });
+  count('pgkiln.ai.requests', { provider: u.service.provider, status: u.status });
+  count('pgkiln.ai.tokens', { provider: u.service.provider, model: u.model.slice(0, 100), type: 'input' }, u.inputTokens);
+  count('pgkiln.ai.tokens', { provider: u.service.provider, model: u.model.slice(0, 100), type: 'output' }, u.outputTokens);
   try {
     await owner.query(
       `insert into meta.ai_usage (app_id, page_no, username, service_id, service, provider, model, source, input_tokens, output_tokens, duration_ms, status, message)