pgkiln 0.69.0 → 0.71.0

package/db/migrations/138_app_utilities.sql

@@ -0,0 +1,153 @@
+-- =====================================================================
+-- 138: an application's Utilities (sprint 138, AP-5; APEX: Application
+--      Utilities: Change History, Attribute Dictionary / UI defaults)
+--
+-- meta.app_snapshot: the application's export (meta.export_app) after the
+--   last recorded change. The builder compares it with a new export after
+--   each change (src/history.ts, the working copies' component split) and
+--   keeps what changed per component in meta.component_change.
+-- meta.component_change: one row per component that a change added,
+--   changed or deleted: its id in the one-file-per-component layout
+--   (src/appfiles.ts, e.g. pages/0003/items/p3_sal), a label, the page,
+--   the component's files before and after ({"path": "text"}), who (a
+--   developer, or null for the command line / MCP server) and when.
+--   Installation data: not exported, kept by import --replace.
+-- meta.ui_default: UI defaults per table column (APEX: Attribute
+--   Dictionary / Table UI Defaults): label, format mask, help, alignment
+--   and list of values. The page wizards and the Create Application wizard
+--   take the label from meta.wizard_column_label (redefined below: a UI
+--   default wins); a form item made by a wizard also gets the column's
+--   format mask, help and list of values (meta.ui_default_item, a trigger
+--   on meta.item that only acts right after meta.wizard_column_label named
+--   a column with a UI default in the same transaction).
+--   Installation data, keyed by schema, table and column names (not oids:
+--   they survive a dump and restore). Not exported with an application.
+-- =====================================================================
+
+create table meta.app_snapshot (
+  app_id   int primary key references meta.app (id) on delete cascade,
+  doc      jsonb not null,
+  taken_at timestamptz not null default now()
+);
+comment on table meta.app_snapshot is
+  'The application''s export after its last recorded change: what the next change is compared with (change history, 138)';
+
+create table meta.component_change (
+  id          bigint generated always as identity primary key,
+  app_id      int not null references meta.app (id) on delete cascade,
+  component   text not null check (length(component) <= 500),
+  label       text not null,
+  page_no     int,
+  op          text not null check (op in ('added', 'changed', 'deleted')),
+  before      jsonb,
+  after       jsonb,
+  changed_by  text,
+  source      text not null default 'builder' check (source in ('builder', 'import', 'upgrade')),
+  changed_at  timestamptz not null default now()
+);
+create index component_change_app_idx on meta.component_change (app_id, changed_at desc);
+create index component_change_component_idx on meta.component_change (app_id, component, changed_at desc);
+comment on table meta.component_change is
+  'Change history per component (138): the component''s files before and after a change, who and when';
+
+create table meta.ui_default (
+  id           int generated always as identity primary key,
+  schema_name  text not null check (schema_name ~ '^[^\s]{1,63}$'),
+  table_name   text not null check (table_name ~ '^[^\s]{1,63}$'),
+  column_name  text not null check (length(column_name) between 1 and 63),
+  label        text check (length(label) <= 200),
+  format_mask  text check (format_mask ~ '^[A-Za-z0-9GDLSCFM.,:/ \-]{1,60}$'),
+  help         text check (length(help) <= 4000),
+  alignment    text check (alignment in ('start', 'center', 'end')),
+  lov          text check (length(lov) <= 4000),
+  updated_by   text,
+  updated_at   timestamptz not null default now(),
+  unique (schema_name, table_name, column_name)
+);
+comment on table meta.ui_default is
+  'UI defaults per table column (APEX: Attribute Dictionary, 138): label, format mask, help, alignment, list of values; used by the page wizards';
+
+-- the UI default of a table's column, or null
+create function meta.ui_default_of(p_table regclass, p_col text) returns meta.ui_default
+language sql stable as $$
+  select d.* from meta.ui_default d
+    join pg_class c on c.oid = p_table join pg_namespace n on n.oid = c.relnamespace
+   where d.schema_name = n.nspname and d.table_name = c.relname and d.column_name = p_col
+$$;
+
+-- (097) a column's label for the generators: (138) its UI default's label wins; a UI default also
+-- tells meta.ui_default_item which column the next wizard item is for (a transaction-local setting)
+create or replace function meta.wizard_column_label(p_table regclass, p_col text) returns text
+language plpgsql stable as $$
+declare
+  v_ui      meta.ui_default := meta.ui_default_of(p_table, p_col);
+  v_comment text;
+  v_rel     text := lower((select relname from pg_class where oid = p_table));
+  v_fk      boolean;
+  v_pk      boolean;
+  v_base    text := p_col;
+  v_rest    text;
+  l         text := lower(p_col);
+begin
+  if v_ui.id is not null then
+    perform set_config('pgkiln.ui_default_col', p_table::oid::text || '.' || p_col, true);
+    if nullif(btrim(v_ui.label), '') is not null then
+      return btrim(v_ui.label);
+    end if;
+  end if;
+  select meta.wizard_short(col_description(p_table, a.attnum), 60) into v_comment
+    from pg_attribute a where a.attrelid = p_table and a.attname = p_col and not a.attisdropped;
+  if v_comment is not null then
+    return v_comment;
+  end if;
+  select c.fk_table is not null, c.is_pk into v_fk, v_pk from meta.wizard_catalog(p_table) c where c.column_name = p_col;
+  if v_fk and not v_pk then
+    v_rest := regexp_replace(p_col, '_?(id|no|num|nr|code|key|fk)$', '', 'i');
+    if length(v_rest) >= 2 then
+      v_base := v_rest;
+    end if;
+  elsif length(l) >= 4 and left(l, 1) = left(v_rel, 1) and not (meta.wizard_abbreviations() ? l) and not meta.wizard_is_word(l)
+        and meta.wizard_is_word(substr(l, 2)) then
+    -- a column named after the table's first letter: ename, dname
+    v_base := substr(p_col, 2);
+  end if;
+  return meta.wizard_label(v_base);
+end
+$$;
+
+-- a form item a wizard is inserting: the column's format mask, help text and list of values
+create function meta.ui_default_item() returns trigger
+language plpgsql as $$
+declare
+  v_mark  text := current_setting('pgkiln.ui_default_col', true);
+  v_table regclass;
+  v_ui    meta.ui_default;
+begin
+  if coalesce(v_mark, '') = '' or new.source_column is null or new.region_id is null then
+    return new;
+  end if;
+  select to_regclass(r.table_name) into v_table from meta.region r where r.id = new.region_id and r.type = 'form';
+  if v_table is null or v_mark <> v_table::oid::text || '.' || new.source_column then
+    return new;
+  end if;
+  perform set_config('pgkiln.ui_default_col', '', true);
+  v_ui := meta.ui_default_of(v_table, new.source_column);
+  if v_ui.id is null or new.type in ('hidden', 'file') then
+    return new;
+  end if;
+  if v_ui.format_mask is not null and new.type in ('number', 'date', 'datetime', 'display', 'text') then
+    new.config := coalesce(new.config, '{}') || jsonb_build_object('format_mask', v_ui.format_mask);
+  end if;
+  if nullif(btrim(v_ui.help), '') is not null then
+    new.help := btrim(v_ui.help);
+  end if;
+  if nullif(btrim(v_ui.lov), '') is not null and new.type in ('text', 'number', 'select') then
+    new.type := 'select';
+    new.lov := btrim(v_ui.lov);
+  end if;
+  return new;
+end
+$$;
+create trigger item_ui_default before insert on meta.item for each row execute function meta.ui_default_item();
+
+revoke all on function meta.ui_default_of(regclass, text), meta.ui_default_item() from public;

package/docs/apex-feature-parity.md

@@ -7,13 +7,13 @@ open item and open an issue or pull request; see [CONTRIBUTING.md](../CONTRIBUTI
 Legend: ✅ available · 🟡 partial (see notes) · ❌ not yet · ➖ not planned (a deliberate choice,
 or better served by the PostgreSQL ecosystem; see the notes and [extensions](guide/15-extensions.md))
 
-Last reviewed: 2026-10-27 against **APEX 26.2** (sprint 135: full-text search configurations, APEX's Oracle Text search type on PostgreSQL full-text search with stemming, ranking, highlights, *Did you mean* and *Add full-text search* in Table Properties (AP-2); sprint 134: the builder also in Italiano, 中文 (简体), 中文 (繁體), 日本語 and 한국어, APEX's ten builder languages plus Nederlands (SEC-5); sprints 121, 123–125: the builder in Deutsch, English, Español, Français, Nederlands and Português, step by step: the frame, sign-in, Workspace home, App Builder, Page Designer menus, the SQL Workshop's home, SQL Worksheet, Object Browser and Table Properties, Shared Components, application settings, users, identity providers, developers and workspaces (WS-7); sprint 122: *Ask in your own words* sets faceted search and smart filter facets, smart filters read a typed phrase (WS-5), and Sample Maps, Sample Approvals, Sample Data Loading and Sample Files in the App Gallery (WS-8); sprint 120: the App Gallery's single-topic sample apps (charts, cards, calendar, interactive grids, dynamic actions, reporting), the UX Pattern Catalog and a Utility Apps tab with Lookup Lists, Release Notes and Announcements (WS-8); sprint 119: data security per table, a roles × columns matrix and masked values per application role in a masking view, the same identity for pages, AI tools, REST, AutoREST and MCP (WS-13); sprint 118: Administration → Mail queue with delivery per hour and per workspace, the slowest provider calls and failures with Retry and Purge, a workspace's own mail service, and workspace network access lists that narrow the installation's allow-list (WS-9); sprint 117: Pillar Light and Pillar Dark navigation appearances with a header strip, clearer navigation tree states, subtle colour utilities, RTL; sprint 116: the comparison moved from 26.1 to 26.2, with a section for the 26.2 workspace items WS-1 … WS-13 and OCI managed identities; the App Builder list with Updated by, working copies and the lock; `pgkiln import --only`, a file-level import; stale rows on facet menus and blueprints fixed; sprint 115: popup LOVs that load on scroll, Wait Popup dynamic actions and dynamic actions on menu entries; sprint 114: Workflow 26.2 with custom task outcomes, task events and notifications, Send E-Mail and draft steps, migrating running instances and the diagram as SVG / PNG; sprint 113: Team Development with issues, labels, milestones, templates, a board and a set-up wizard; sprint 112: AI interactive reports with chips, Undo, computed columns and a phrase parser that needs no AI service; sprint 111: AI Agents with tools as a shared component, a Navigate tool with checksummed URLs, Gemini and OpenAI-compatible services; sprint 110: Data Reporter as a workspace tool with datasets, reporting applications, editors and viewers, published reports with stable URLs and pins; sprint 109: the Workspace home above the App Builder and SQL Workshop, with a summary, top applications, users and developers, and an optional release check; sprint 108: the code editor's syntax colours in the builder's light and dark themes, read-only SQL highlighted, the Data Modeler in dark mode; sprint 107: a transaction mode in the SQL Worksheet with Commit and Rollback; DA-18: JavaScript (MLE) not planned, plv8 where installed; sprint 106: the change log of DDL change sets with Flyway, Liquibase and SQL downloads; sprint 104: RESTful Services modules, templates and handlers with PL/pgSQL and media handlers, privileges, OpenAPI and Try it; sprint 103: Schema Export / Import with pg_dump and pg_restore; sprint 102: the SQL Monitor with live sessions, Top SQL and a statement's plan; sprint 101: Scheduling of pg_cron jobs with a schedule builder, run now and run history; sprint 100: RESTful Services, tables and views published as REST endpoints with paging, filters, keys and OpenAPI; sprint 99: Administration → Database Users for PostgreSQL roles; sprint 98: the Data Modeler with relational diagrams, DDL and a data dictionary; sprint 97: charts of a query in the worksheet, saved charts and their dashboard; sprint 96: the SQL Workshop's Launchpad with pins and tool groups, the builder's search with Ctrl+K; sprint 95: Table Properties: create, edit or copy a table in a form with a DDL preview and Apply in one transaction; sprint 94: an object's menu with Open in a panel, Quick DDL, Add index / trigger / policy and Drop with dependents; sprint 93: worksheets saved as SQL Scripts with tabs and a Files list, Format, Convert case, find and replace, bind and substitution variables; sprint 92: the worksheet's Query Result with sort, value dialog, copy and downloads, plans as a tree with the slowest step and misestimates, SQL History with status, search and run again; sprint 91: the SQL Worksheet like Database Actions' SQL: navigator, Run Statement at the cursor and Run Script with a log per statement, Explain Plan, Autotrace, notices, history, Run as an application role; sprint 90: Comment Out in the page designer, gallery labels in title case; sprint 89: the Object Browser's schema, one row of tabs, blank NULLs, Modify column; sprint 88: home cards with colour bands and round icons, the hero on the page background, a page footer with the version and Back to top; sprint 87: the Create Application wizard reloads the page list for a schema, RLS badges, the alias from the name; sprint 86: the page designer by page number, HTML error pages in the builder; sprint 85: the Form Designer, beyond APEX; sprint 84: the date picker, facet menus; sprint 83: Component Settings and Component Groups; sprint 82: Report Queries; sprint 81: Application Computations and Shortcuts in Shared Components; sprint 80: the master grid's first row selected when the page opens and after a search; grid cells as text with their format mask until edited, with cell navigation by arrow keys, Enter, F2 and Escape; sprint 79: generated dashboards with sums, donuts and lines, leaving out charts that say nothing; applications open in their own light or dark mode until the user chooses, per application; a user menu with Appearance and Sign in when signed out; the developer toolbar's App and Page texts and debug state; the report search's column scope in the magnifier; sprint 78: generated faceted search reports with one column per foreign key, the faceted search's total row count, Show all and Yes/No values, one search field, friendly headings and number formats in generated grids and master-detail pages, friendly names in the Create Application wizard's page list; sprint 77: the Page Designer's layout and tree by display position, button positions, the tree's context menu with Duplicate and Copy to other page, Show Common / Show All, Go to group and the Template Options dialog; display positions, button positions and side-column page templates at runtime; sprint 76: the interactive report's menus and pagination, date items in the date format; sprint 75: the SQL Workshop's Object Browser and tabs; sprint 74: the builder's information architecture: Shared Components grid, Settings tabs, application home search and tasks; sprint 73: the Create Application wizard on one page with page types and features; sprint 72: the runtime chrome compared with APEX 26.2's: the developer toolbar, the Iris look, the navigation bar's Help menu and Install button; sprint 71: generated applications compared with APEX 26.2's: labels, foreign key names in reports, file columns, format masks, the Home page and the dashboard; sprint 70: treemap, sunburst and timeline charts; sprint 69: dragging tasks on a Gantt chart; sprint 68: the Data Reporter's welcome page, Find my workspace; sprint 67: REST source catalogs from OpenAPI documents, a workspace's export and import (two rows added); sprint 66: a blueprint from an existing application; sprint 65: facet charts; sprint 64: approval vacation rules and expiration policies; sprint 63: range, box plot and stock charts; sprint 62: workspace preferences (SQL Workshop and RESTful services per workspace), extension links, Manage backups across applications, SQL Workshop utilities with object reports, About Database and a database monitor; sprint 61: the builder's screens compared with APEX 26.1: the workspace sign-in page, the Administration menu with workspace message, environment banner and utilization, the SQL Workshop home, the App Gallery, application groups and cross application reports (four rows added); sprint 60: isolated workspaces with their own database logins, row-level security on pgkiln's tables and workspace database roles, workspace administrators; sprint 59: the Page Designer's help pane, Quick edit from the developer toolbar; sprint 58: page groups; sprint 57: region templates hero, title bar, buttons container, inline dialog and drawer, wizard with wizard progress, the carousel; sprint 56: Generate DDL and Schema Comparison in the SQL Workshop, `pgkiln ddl` and `pgkiln compare`; sprint 55: an editable login page with a Login region and the Minimal page template, Forgot password through the application's mail service; sprint 54: interactive grid views, the single row view, group by and chart; sprint 53: application settings, user preferences and items kept per user, dynamic translations, `meta.data_export` and data export downloads, display image and geocoded address items; sprint 52: every dynamic action event and action, Ajax callbacks, an error handling function, the session timeout warning; sprint 51: checked imports, application backups, availability and Run only, feedback, type-specific attribute help; sprint 50: lost update detection, warn on unsaved changes, the URL and search regions with search configurations, the developer toolbar with a session state viewer, and e-mail through SMTP with OAuth2, Microsoft Graph, Amazon SES and HTTP APIs; import checks, application availability, property help and e-mail compared again; 2026-10-06: pgkiln 0.31.0, in progress: static application files and the Execute JavaScript dynamic action; region, item, dynamic action and process plug-ins; conditional and dynamic theme styles; XML and Excel in `meta.parse_data`, zips in SQL, `meta.v_boolean`; file items in S3-compatible object storage; map layers by the visible area and as vector tiles; a graphical query builder; tenants for workflows and tasks; application files as YAML and region static IDs; Lucide icons and icon modifiers; PWA push notifications; 0.30.0: 136 icons and an icon picker; an axe-core accessibility audit; cropping pictures; session sharing between applications; twenty-two built-in languages; 0.29.0: workspaces; the Iris base style; drawers; built-in template components including the metric card; Theme Roller dark-mode colours, live preview and template options on items and report columns; report selection across pages; instance settings; fourteen built-in languages; 0.28.0: AI with Claude and OpenAI; 0.27.0: Data Reporter; sample data generator; create application from several sheets, pasted data or existing tables; 0.26.0: working copies with a three-way merge; theme, library and boilerplate applications with subscriptions; 0.25.0: Gantt, pyramid and polar charts; map layers, clustering and server-side spatial filters; REST data sources that write back from forms and grids and synchronise into tables, OAuth2 password and refresh-token grants; debug messages per request and an install/upgrade log; `meta.web_request()` and `meta.parse_data()`; Theme Roller style variants and template options; 0.24.0: automations with several actions, error handling per row and runs from SQL; invoke-API workflow steps; Unload Data in the Data Workshop; create page wizards for cards, calendar, chart, map, faceted search, form and master-detail; create an application from a file; 0.23.0: interactive grid aggregates, frozen/moved/resized columns, layouts and saved grid reports, master-detail, row actions and copy/paste; download processes, execution chains in the background, workflow processes, branches to a function's URL or another app, the Dialog Closed event; number format masks, automatic time zone, runtime messages in German, French and Spanish; SQL scripts, Quick SQL, a query builder, XML loading and data load definitions; custom authentication, lists, page and application locks with developer comments, supporting objects; 0.22.0: keyset paging, report PDFs and REST collections streamed from a cursor, database-account authentication; 0.21.0: HTTP-header authentication behind a reverse proxy; 0.20.0: a popup list of values with server-side search; 0.19.0: row-range pagination, maximum row counts and row limits, lazy loading and caching of regions, streamed CSV/Excel downloads; 0.18.0: calendar week/day/list views with drag and drop, bubble/gauge/funnel/radar charts and drill-down, smart filters, a region display selector and more facet types, computations, conditional branches, build options, menu buttons, REST data sources and web credentials, rich text/Markdown, rating, combobox, date range and QR code items; 0.17.0: an App Builder home, workspace dashboard and utilities like APEX's; 0.16.0: a Page Designer with drag-and-drop layout, a code editor with autocomplete, template components and plug-ins, parallel branches and versions of workflows, the `pgkiln` command line with one file per component; 0.15.0: drop and paste files, heat maps, filtering a report by the map area; 0.14.0: stacked, combo, scatter and pie charts, several files per upload item; 0.13.0: map and tree regions; 0.12.0: REST modules in the builder; 0.11.0: workflows and Progressive Web Apps; 0.10.0: LDAP, SAML, "Keep me signed in", document templates, JSON loading, approvals and the task list; pgkiln installs no application, HR is an example).
+Last reviewed: 2026-11-03 against **APEX 26.2** (sprint 138: an application's Utilities tab with a dashboard, database object dependencies, change history per component, Upgrade application, UI defaults (APEX's Attribute Dictionary), application and page checksums and an icon browser (AP-5); sprint 137: Create page as a grid of page types with previews, the page types interactive report, smart filters, search page, data loading, tree, timeline, media list, content row, comments, dashboard, wizard, unified task list and workflow console, a Feature tab with nine features that install once, and Create page as copy with shared components mapped or copied (AP-3); sprint 136: vector providers (an AI service with an embedding model or a SQL function), `meta.embed`, *Add vector column* in Table Properties with an HNSW index and a queue that keeps embeddings current, search types vector and hybrid (reciprocal rank fusion with full-text) and a Retrieve (RAG) tool for AI agents, all as the app's role through RLS, on pgvector (AP-1); sprint 135: full-text search configurations, APEX's Oracle Text search type on PostgreSQL full-text search with stemming, ranking, highlights, *Did you mean* and *Add full-text search* in Table Properties (AP-2); sprint 134: the builder also in Italiano, 中文 (简体), 中文 (繁體), 日本語 and 한국어, APEX's ten builder languages plus Nederlands (SEC-5); sprints 121, 123–125: the builder in Deutsch, English, Español, Français, Nederlands and Português, step by step: the frame, sign-in, Workspace home, App Builder, Page Designer menus, the SQL Workshop's home, SQL Worksheet, Object Browser and Table Properties, Shared Components, application settings, users, identity providers, developers and workspaces (WS-7); sprint 122: *Ask in your own words* sets faceted search and smart filter facets, smart filters read a typed phrase (WS-5), and Sample Maps, Sample Approvals, Sample Data Loading and Sample Files in the App Gallery (WS-8); sprint 120: the App Gallery's single-topic sample apps (charts, cards, calendar, interactive grids, dynamic actions, reporting), the UX Pattern Catalog and a Utility Apps tab with Lookup Lists, Release Notes and Announcements (WS-8); sprint 119: data security per table, a roles × columns matrix and masked values per application role in a masking view, the same identity for pages, AI tools, REST, AutoREST and MCP (WS-13); sprint 118: Administration → Mail queue with delivery per hour and per workspace, the slowest provider calls and failures with Retry and Purge, a workspace's own mail service, and workspace network access lists that narrow the installation's allow-list (WS-9); sprint 117: Pillar Light and Pillar Dark navigation appearances with a header strip, clearer navigation tree states, subtle colour utilities, RTL; sprint 116: the comparison moved from 26.1 to 26.2, with a section for the 26.2 workspace items WS-1 … WS-13 and OCI managed identities; the App Builder list with Updated by, working copies and the lock; `pgkiln import --only`, a file-level import; stale rows on facet menus and blueprints fixed; sprint 115: popup LOVs that load on scroll, Wait Popup dynamic actions and dynamic actions on menu entries; sprint 114: Workflow 26.2 with custom task outcomes, task events and notifications, Send E-Mail and draft steps, migrating running instances and the diagram as SVG / PNG; sprint 113: Team Development with issues, labels, milestones, templates, a board and a set-up wizard; sprint 112: AI interactive reports with chips, Undo, computed columns and a phrase parser that needs no AI service; sprint 111: AI Agents with tools as a shared component, a Navigate tool with checksummed URLs, Gemini and OpenAI-compatible services; sprint 110: Data Reporter as a workspace tool with datasets, reporting applications, editors and viewers, published reports with stable URLs and pins; sprint 109: the Workspace home above the App Builder and SQL Workshop, with a summary, top applications, users and developers, and an optional release check; sprint 108: the code editor's syntax colours in the builder's light and dark themes, read-only SQL highlighted, the Data Modeler in dark mode; sprint 107: a transaction mode in the SQL Worksheet with Commit and Rollback; DA-18: JavaScript (MLE) not planned, plv8 where installed; sprint 106: the change log of DDL change sets with Flyway, Liquibase and SQL downloads; sprint 104: RESTful Services modules, templates and handlers with PL/pgSQL and media handlers, privileges, OpenAPI and Try it; sprint 103: Schema Export / Import with pg_dump and pg_restore; sprint 102: the SQL Monitor with live sessions, Top SQL and a statement's plan; sprint 101: Scheduling of pg_cron jobs with a schedule builder, run now and run history; sprint 100: RESTful Services, tables and views published as REST endpoints with paging, filters, keys and OpenAPI; sprint 99: Administration → Database Users for PostgreSQL roles; sprint 98: the Data Modeler with relational diagrams, DDL and a data dictionary; sprint 97: charts of a query in the worksheet, saved charts and their dashboard; sprint 96: the SQL Workshop's Launchpad with pins and tool groups, the builder's search with Ctrl+K; sprint 95: Table Properties: create, edit or copy a table in a form with a DDL preview and Apply in one transaction; sprint 94: an object's menu with Open in a panel, Quick DDL, Add index / trigger / policy and Drop with dependents; sprint 93: worksheets saved as SQL Scripts with tabs and a Files list, Format, Convert case, find and replace, bind and substitution variables; sprint 92: the worksheet's Query Result with sort, value dialog, copy and downloads, plans as a tree with the slowest step and misestimates, SQL History with status, search and run again; sprint 91: the SQL Worksheet like Database Actions' SQL: navigator, Run Statement at the cursor and Run Script with a log per statement, Explain Plan, Autotrace, notices, history, Run as an application role; sprint 90: Comment Out in the page designer, gallery labels in title case; sprint 89: the Object Browser's schema, one row of tabs, blank NULLs, Modify column; sprint 88: home cards with colour bands and round icons, the hero on the page background, a page footer with the version and Back to top; sprint 87: the Create Application wizard reloads the page list for a schema, RLS badges, the alias from the name; sprint 86: the page designer by page number, HTML error pages in the builder; sprint 85: the Form Designer, beyond APEX; sprint 84: the date picker, facet menus; sprint 83: Component Settings and Component Groups; sprint 82: Report Queries; sprint 81: Application Computations and Shortcuts in Shared Components; sprint 80: the master grid's first row selected when the page opens and after a search; grid cells as text with their format mask until edited, with cell navigation by arrow keys, Enter, F2 and Escape; sprint 79: generated dashboards with sums, donuts and lines, leaving out charts that say nothing; applications open in their own light or dark mode until the user chooses, per application; a user menu with Appearance and Sign in when signed out; the developer toolbar's App and Page texts and debug state; the report search's column scope in the magnifier; sprint 78: generated faceted search reports with one column per foreign key, the faceted search's total row count, Show all and Yes/No values, one search field, friendly headings and number formats in generated grids and master-detail pages, friendly names in the Create Application wizard's page list; sprint 77: the Page Designer's layout and tree by display position, button positions, the tree's context menu with Duplicate and Copy to other page, Show Common / Show All, Go to group and the Template Options dialog; display positions, button positions and side-column page templates at runtime; sprint 76: the interactive report's menus and pagination, date items in the date format; sprint 75: the SQL Workshop's Object Browser and tabs; sprint 74: the builder's information architecture: Shared Components grid, Settings tabs, application home search and tasks; sprint 73: the Create Application wizard on one page with page types and features; sprint 72: the runtime chrome compared with APEX 26.2's: the developer toolbar, the Iris look, the navigation bar's Help menu and Install button; sprint 71: generated applications compared with APEX 26.2's: labels, foreign key names in reports, file columns, format masks, the Home page and the dashboard; sprint 70: treemap, sunburst and timeline charts; sprint 69: dragging tasks on a Gantt chart; sprint 68: the Data Reporter's welcome page, Find my workspace; sprint 67: REST source catalogs from OpenAPI documents, a workspace's export and import (two rows added); sprint 66: a blueprint from an existing application; sprint 65: facet charts; sprint 64: approval vacation rules and expiration policies; sprint 63: range, box plot and stock charts; sprint 62: workspace preferences (SQL Workshop and RESTful services per workspace), extension links, Manage backups across applications, SQL Workshop utilities with object reports, About Database and a database monitor; sprint 61: the builder's screens compared with APEX 26.1: the workspace sign-in page, the Administration menu with workspace message, environment banner and utilization, the SQL Workshop home, the App Gallery, application groups and cross application reports (four rows added); sprint 60: isolated workspaces with their own database logins, row-level security on pgkiln's tables and workspace database roles, workspace administrators; sprint 59: the Page Designer's help pane, Quick edit from the developer toolbar; sprint 58: page groups; sprint 57: region templates hero, title bar, buttons container, inline dialog and drawer, wizard with wizard progress, the carousel; sprint 56: Generate DDL and Schema Comparison in the SQL Workshop, `pgkiln ddl` and `pgkiln compare`; sprint 55: an editable login page with a Login region and the Minimal page template, Forgot password through the application's mail service; sprint 54: interactive grid views, the single row view, group by and chart; sprint 53: application settings, user preferences and items kept per user, dynamic translations, `meta.data_export` and data export downloads, display image and geocoded address items; sprint 52: every dynamic action event and action, Ajax callbacks, an error handling function, the session timeout warning; sprint 51: checked imports, application backups, availability and Run only, feedback, type-specific attribute help; sprint 50: lost update detection, warn on unsaved changes, the URL and search regions with search configurations, the developer toolbar with a session state viewer, and e-mail through SMTP with OAuth2, Microsoft Graph, Amazon SES and HTTP APIs; import checks, application availability, property help and e-mail compared again; 2026-10-06: pgkiln 0.31.0, in progress: static application files and the Execute JavaScript dynamic action; region, item, dynamic action and process plug-ins; conditional and dynamic theme styles; XML and Excel in `meta.parse_data`, zips in SQL, `meta.v_boolean`; file items in S3-compatible object storage; map layers by the visible area and as vector tiles; a graphical query builder; tenants for workflows and tasks; application files as YAML and region static IDs; Lucide icons and icon modifiers; PWA push notifications; 0.30.0: 136 icons and an icon picker; an axe-core accessibility audit; cropping pictures; session sharing between applications; twenty-two built-in languages; 0.29.0: workspaces; the Iris base style; drawers; built-in template components including the metric card; Theme Roller dark-mode colours, live preview and template options on items and report columns; report selection across pages; instance settings; fourteen built-in languages; 0.28.0: AI with Claude and OpenAI; 0.27.0: Data Reporter; sample data generator; create application from several sheets, pasted data or existing tables; 0.26.0: working copies with a three-way merge; theme, library and boilerplate applications with subscriptions; 0.25.0: Gantt, pyramid and polar charts; map layers, clustering and server-side spatial filters; REST data sources that write back from forms and grids and synchronise into tables, OAuth2 password and refresh-token grants; debug messages per request and an install/upgrade log; `meta.web_request()` and `meta.parse_data()`; Theme Roller style variants and template options; 0.24.0: automations with several actions, error handling per row and runs from SQL; invoke-API workflow steps; Unload Data in the Data Workshop; create page wizards for cards, calendar, chart, map, faceted search, form and master-detail; create an application from a file; 0.23.0: interactive grid aggregates, frozen/moved/resized columns, layouts and saved grid reports, master-detail, row actions and copy/paste; download processes, execution chains in the background, workflow processes, branches to a function's URL or another app, the Dialog Closed event; number format masks, automatic time zone, runtime messages in German, French and Spanish; SQL scripts, Quick SQL, a query builder, XML loading and data load definitions; custom authentication, lists, page and application locks with developer comments, supporting objects; 0.22.0: keyset paging, report PDFs and REST collections streamed from a cursor, database-account authentication; 0.21.0: HTTP-header authentication behind a reverse proxy; 0.20.0: a popup list of values with server-side search; 0.19.0: row-range pagination, maximum row counts and row limits, lazy loading and caching of regions, streamed CSV/Excel downloads; 0.18.0: calendar week/day/list views with drag and drop, bubble/gauge/funnel/radar charts and drill-down, smart filters, a region display selector and more facet types, computations, conditional branches, build options, menu buttons, REST data sources and web credentials, rich text/Markdown, rating, combobox, date range and QR code items; 0.17.0: an App Builder home, workspace dashboard and utilities like APEX's; 0.16.0: a Page Designer with drag-and-drop layout, a code editor with autocomplete, template components and plug-ins, parallel branches and versions of workflows, the `pgkiln` command line with one file per component; 0.15.0: drop and paste files, heat maps, filtering a report by the map area; 0.14.0: stacked, combo, scatter and pie charts, several files per upload item; 0.13.0: map and tree regions; 0.12.0: REST modules in the builder; 0.11.0: workflows and Progressive Web Apps; 0.10.0: LDAP, SAML, "Keep me signed in", document templates, JSON loading, approvals and the task list; pgkiln installs no application, HR is an example).
 
 ## At a glance
 
 | Area | ✅ | 🟡 | ❌ | ➖ | In short |
 |---|---:|---:|---:|---:|---|
-| App Builder and development | 21 | 0 | 0 | 0 | Page Designer with drag-and-drop and a code editor, wizards, search, where used, an Advisor, a CLI with one file per component, page locks and comments, supporting objects, working copies with a three-way merge, theme/library/boilerplate apps with subscriptions; App Builder AI (pages, SQL and table descriptions) |
+| App Builder and development | 22 | 0 | 0 | 0 | Page Designer with drag-and-drop and a code editor, wizards, search, where used, an Advisor, a CLI with one file per component, page locks and comments, supporting objects, working copies with a three-way merge, theme/library/boilerplate apps with subscriptions; App Builder AI (pages, SQL and table descriptions) |
 | Regions | 23 | 0 | 0 | 0 | All everyday regions, a search region over search configurations and a URL region; twenty-two chart types with drill-down; calendars with week/day/list views and drag and drop; faceted search, smart filters and a region display selector; interactive reports with breaks, aggregates, highlights, compute, group by, pivot, chart view and saved reports; interactive grids with single row, group by and chart views; maps (with vector tiles) and trees; template components; row ranges, lazy loading and region caching for large tables |
 | Items | 13 | 0 | 0 | 0 | All common items, file upload (several files per item), rich text and Markdown editors, star rating, combobox, date range, QR code, password reveal, display image and geocoded address |
 | Logic and processing | 18 | 0 | 0 | 1 | User preferences and application settings; all dynamic action events and actions, Ajax callbacks and an error handling function; Core APEX model complete with computations, conditional branches, build options and menu buttons, download, chain and workflow processes; JavaScript from static application files in dynamic actions; region, item, dynamic action and process plug-ins |
@@ -24,7 +24,7 @@ Last reviewed: 2026-10-27 against **APEX 26.2** (sprint 135: full-text search co
 | 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) | 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 eleven languages (APEX's ten and Nederlands) |
-| **Total** | **161** | **0** | **0** | **4** | 165 APEX features compared: 98% available, none missing, 4 deliberately not planned |
+| **Total** | **162** | **0** | **0** | **4** | 166 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
@@ -41,7 +41,7 @@ the 26.2 comparison.)
 |---|---|---|
 | App Builder: create, edit, delete, run apps | ✅ | Builder at `/builder` |
 | Create application wizard | ✅ | Blank app with its own database role and schema, started from a **boilerplate application** if wanted; **from a file**: CSV/TSV/XLSX/JSON/XML, where an Excel workbook with several sheets (or JSON with several arrays) becomes several tables, with a preview to include or leave out each sheet, edit table/column names, types and primary keys, and **foreign keys proposed** from matching columns; **from pasted data** (CSV/TSV text); **from existing tables** (pick the tables and views of a schema). Each gives a report and form per table, navigation and an optional dashboard (a chart per table), plus an optional faceted search for a single table, all created in one transaction. (sprint 73) **One page like APEX's**: name, icon and description, appearance (theme style, side or top menu, accent), a **page type per table** (interactive report with form, faceted search, cards, calendar, master detail, interactive grid, report, none; large tables proposed as a grid), **features** (About page, access control roles, activity reporting, feedback, theme style selection, PWA, push), settings (alias, authentication, first user, language) and a boilerplate under Advanced; a progress message, then straight to the new application. (sprint 71) The generated pages read like APEX's: human labels (abbreviations, run-together words, column and table comments), plural page and menu names with singular form titles, foreign keys shown by the parent's name in reports, `bytea` columns as one file item with their name/mime/size/updated columns, number format masks, a pencil per report row, the Dashboard after Home with *(none)* and top-N charts, and a Home page with a hero and a card per page. (sprint 66) **From a blueprint** (26.1 blueprints): a reviewed JSON spec of tables, pages and sample data, or a blueprint made from an existing application (see [Blueprints](#workflow-automation-and-ai)) |
-| Create page wizards | ✅ | Report and form, interactive grid, form, cards, calendar, chart, map, faceted search and master-detail (stacked grids) from any table or view, with defaults from the catalog (columns, key, dates, positions, foreign keys), an optional modal form page and a navigation entry; also from SQL (`meta.generate_page`). No side-by-side or drill-down master-detail, no wizard for smart filters or trees |
+| Create page wizards, Create a Page (Component, Feature), Create Page as Copy | ✅ | (sprint 137, AP-3) **Create page** is a grid of page types with small previews like APEX's: 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; the table step only for the types on a table, with defaults from the catalog (columns, key, dates, positions, foreign keys; a tree's parent from a self-referencing foreign key; a wizard's steps with a progress list; a data load definition and its page), an optional modal form page and a navigation entry; also from SQL (`meta.generate_page`). **Feature** (also App home → Add feature page): Access control, Activity reporting, Configuration options (configurable build options as switches for administrators), E-mail reporting (a weekly activity report by mail), Feedback, About, Login page, Theme style selection, Push notifications; each lists what it adds, installs once and greys out ([chapter 3](guide/03-builder.md#add-feature)). **Copy**: a page of this or another application of the workspace under a new number and name, `P<n>_` items renamed, the shared components it uses mapped to the target's or copied ([chapter 3](guide/03-builder.md#create-page-as-copy)). No Classic Report type (the interactive report covers it), no side-by-side or drill-down master-detail
 | Page Designer | ✅ | IDE-style window (dark or light): component tree, a layout canvas with drag and drop (with keyboard and button alternatives) and a gallery of regions, items and buttons, a filterable property editor; undo/redo; panes become tabs on phones. Settings forms for report, grid, chart, cards, calendar, faceted search, smart filters, display selector, map, tree and template component regions. A code editor for SQL, PL/pgSQL, JSON and HTML with highlighting and autocomplete of tables, columns and `:ITEM` binds (no extra libraries). Drag and drop needs a mouse; on touch screens the Arrange buttons move components. (sprint 77) The layout draws the page template's display positions (banner, breadcrumb bar, left/right column, body, footer) as drop zones and a region's button positions; the rendering tree groups by position and has a context menu (create in or below, Duplicate, Copy to other page, expand/collapse all, (sprint 90) Comment out with a COMMENTED_OUT build option, delete; no Create Sub Region: no nested regions); the property editor has Common / All, Go to group and a Template Options dialog; a page number in the toolbar. No nested regions (APEX's sub regions) |
 | Shared components | ✅ | (sprint 74) A grid of ten groups with counts like APEX's, a searchable, sortable list per type with Create, and Settings-backed types linking to their Settings tab ([mapping below](#shared-components-apex-links-and-pgkiln)). Navigation menu, **lists** (static entries with nesting, badges, conditions, authorization and build options, or a query; for list regions, the navigation menu and the navigation bar), authorization schemes, build options, lists of values, application items and processes, access control, globalization, template components and plug-ins, web credentials, REST data sources, data load definitions, supporting objects |
 | Export / import | ✅ | `meta.export_app()` / `meta.import_app()`: portable JSON, also in the builder (new applications; `pgkiln import --replace` and the MCP `import_app` update one in place, live for every user at the commit). (sprint 51) **Checked imports**: `pgkiln import --check` (`--dry-run`, `--force`), the MCP import (by default) and the builder's import run the Advisor inside the import's transaction (SQL planned as the application's role: missing tables, columns, functions, types, grants; references) and refuse on errors, so nothing changes; APEX doesn't check. The version an import replaces is [backed up](guide/03-builder.md#backups) first ([chapter 18](guide/18-cli.md#checking-before-an-import)) |
@@ -54,6 +54,7 @@ the 26.2 comparison.)
 | Theme, library and boilerplate application types (26.1) | ✅ | An application type in Settings ([chapter 3](guide/03-builder.md#application-types-and-subscriptions)): a **theme** app offers its theme (colours, navigation, Theme Roller styles) and template components, a **library** app its lists of values, authorization schemes, build options, template components and lists; other apps **subscribe** (the component is copied), see whether they are in sync, **refresh** one or all, and the master **publishes** to its subscribers (locked apps skipped). A **boilerplate** app is a *Start from* choice in Create application. Subscriptions are not exported; no subscriptions to pages or plug-ins other than template components |
 | Property help in the Page Designer, component reference | ✅ | Help text under most properties in the Page Designer (175 of 266 fields; the obvious ones such as *Title* and *Sequence* have none), and a guide section per region type, item type and button with the columns its SQL must return ([chapter 4](guide/04-pages-and-regions.md#region-types), [5](guide/05-items.md), [6](guide/06-processing.md#buttons)). (sprint 51) A region's *Attributes (JSON)* help shows its own type's keys with a link to its section of the guide. (sprint 59) The **Help pane** under the properties shows the focused property's help, the name it is stored under and the guide section of the component's type |
 | Advisor | ✅ | Per app: every SQL fragment planned (EXPLAIN, as the app's role, rolled back) for syntax, unknown objects, types and grants; PL/pgSQL blocks compiled; references to missing pages, items, lists of values, schemes and layouts; PL/pgSQL functions with `plpgsql_check` when installed. Plus the security checklist |
+| Application Utilities: dashboard, database object dependencies, change history, Upgrade Application, Attribute Dictionary, application and page checksums, icons | ✅ | (sprint 138, AP-5) An application's **Utilities** tab gathers the Advisor, Search, Debug, Activity, Backups, Working copies and Export with an application dashboard and recently updated pages; **Database object dependencies** (every SQL the Advisor plans, parsed as the app's role, with the components that use each object; missing objects and missing grants in red); **Change history** per component with who, when and a diff, for builder changes and every import `--replace` (`CHANGE_HISTORY_DAYS`); **Upgrade application** (date pickers for date columns, popup LOVs for large tables, a navigation appearance) with a preview; **UI defaults** per column (label, format mask, help, alignment, LOV) used by the page and application wizards, seeded from column comments; a SHA-256 **application checksum** with one per page, also in Export's `X-Pgkiln-Checksum` header; an **icon browser** ([chapter 3](guide/03-builder.md#utilities)) |
 | Builder search, "where used" | ✅ | Search over every page and component (names, SQL, settings, help); "Used in" under items, pages, lists of values, schemes and report layouts. No search and replace |
 | AI assistant, pages from natural language, describe tables for LLMs (26.1) | ✅ | **App Builder AI** (administrators choose the builder's AI service): SQL Workshop → AI writes SQL from a question (shown in an editor, never run automatically), explains a query or an error, and describes tables and columns for LLMs (notes, optionally `COMMENT ON`, with AI drafts from names, types and keys only); **Create pages with AI** turns a description into proposed pages that the developer edits and confirms ([chapter 3](guide/03-builder.md)). The model never sees table rows |
 | Sample data source for development (26.1) | ✅ | SQL Workshop → **Sample Data** ([chapter 16](guide/16-files.md#sql-workshop--sample-data)): generators proposed per column from the catalog and column names (names, e-mail addresses, phones, companies, addresses, words and sentences, codes, number/date/time ranges, booleans, value lists from enums and CHECKs, sequences, foreign keys picking existing or newly inserted parent rows, values relative to another column, % nulls; identity/serial/generated columns skipped; unique and simple CHECK constraints respected), rows per table, a seed for repeatable data, preview (inserted and rolled back), insert in one transaction with parents first, download as SQL INSERTs or CSV, saved generator definitions |
@@ -81,11 +82,11 @@ the 26.2 comparison.)
 | Region display selector, tabs | ✅ | Tabs or a select list; regions can share a tab, *Show all*, the choice remembered in the session, `#R<id>` links. Accessible tabs with JavaScript; without it every region shows with links to each |
 | Tree | ✅ | `tree` region from id / parent id / label rows, with icons, links and the first levels open; works without JavaScript |
 | Map region (26.1: vector tiles, bounding box) | ✅ | `map` region: several layers per map, each with its own query (markers, lines and areas from GeoJSON or a PostGIS geometry, heat maps), a legend that switches layers on and off and a colour per layer; marker clustering; popups with links. A report can be filtered by the visible area or by the distance from the map's centre on the server: with PostGIS (`ST_Intersects`/`ST_DWithin`, detected automatically) when installed, otherwise on latitude/longitude (bounding box, haversine). Configurable tile server. (0.31) **Large data sets**: a layer loads only the places in the visible area, again as the map moves (`visible_area`), or is served as **Mapbox Vector Tiles** (`tiles`, MVT 2.1, drawn on canvases with popups; readable by MapLibre, OpenLayers or QGIS), both filtered on the server like the report filter ([chapter 4](guide/04-pages-and-regions.md#map)) |
-| Timeline, comments, media list, avatar template components (26.1: groups, Metric Card) | ✅ | Built in for every application: avatar (groups), badge, comments, media list, metric card and timeline, as regions (one or all rows, the group) and report column templates; an application's own copy replaces a built-in one ([chapter 4](guide/04-pages-and-regions.md#built-in-template-components)) |
+| Timeline, comments, media list, avatar template components (26.1: groups, Metric Card) | ✅ | Built in for every application: avatar (groups), badge, comments, (sprint 137) content row, media list, metric card and timeline, as regions (one or all rows, the group) and report column templates; an application's own copy replaces a built-in one ([chapter 4](guide/04-pages-and-regions.md#built-in-template-components)) |
 | Pagination of large tables (row ranges, maximum row count) | ✅ | Reports and grids page in the database; `"pagination": "range"` shows APEX's "row ranges X to Y" without a total (it reads one row more for *Next*); `max_rows` is a maximum row count (the total is counted over at most max+1 rows: "of more than N"; downloads are capped too); page numbers and sizes are clamped on the server. Cards (500), charts (1000), dynamic content (1000) and lists of values (5000) have configurable row limits. Keyset ("seek") paging on an indexed sort (`"keyset"`), with signed positions |
 | Lazy loading of regions | ✅ | `"lazy": true` on report, chart, cards, dynamic, tree and template component regions: a placeholder, fetched after the page shows (page, condition and authorization re-checked); without JavaScript a link shows the region ([chapter 4](guide/04-pages-and-regions.md#large-tables)) |
 | Region caching (per user, per session, for a duration) | ✅ | `"cache": {"scope": "user" \| "session" \| "all", "seconds": N}` keeps rendered regions in server memory, keyed by app, region, roles, language, the query string and the item values the region uses; a page submit empties it. CSRF tokens and per-user links are never shared. Per server process |
-| Search configurations and the search region (22.2) | ✅ | (sprint 50) Shared Components → **Search configurations**: a table, a query (binds allowed) or a list, the searchable columns, and each result's title, subtitle, description, badge, icon and link. A **search** region searches the ones it names with one field (or a page item): every word in one of the columns, as the app's role with the text as a parameter; results grouped per configuration with the words marked; searches as you type, works without JavaScript; exported; checked by the Advisor ([chapter 4](guide/04-pages-and-regions.md#search-search-region)). (sprint 135) Search type **fulltext** for APEX's *Oracle Text*: a tsvector column or expression (or built from the searchable columns), a text search configuration per application language (`simple` as fallback), `websearch_to_tsquery` for the user's text (phrases, or, -word), the best match first (`ts_rank_cd`) and matched words highlighted (`ts_headline`, escaped); *Did you mean* with `pg_trgm`; SQL Workshop › Table Properties › *Add full-text search* (generated tsvector column and GIN index, previewed, recorded in the Change Log); report search boxes use a tsvector column too; the Advisor warns about a missing GIN index ([full-text search](guide/04-pages-and-regions.md#full-text-search)). No vector search yet (AP-1), no REST data sources or APEX-application search as sources, no custom result templates |
+| Search configurations and the search region (22.2) | ✅ | (sprint 50) Shared Components → **Search configurations**: a table, a query (binds allowed) or a list, the searchable columns, and each result's title, subtitle, description, badge, icon and link. A **search** region searches the ones it names with one field (or a page item): every word in one of the columns, as the app's role with the text as a parameter; results grouped per configuration with the words marked; searches as you type, works without JavaScript; exported; checked by the Advisor ([chapter 4](guide/04-pages-and-regions.md#search-search-region)). (sprint 135) Search type **fulltext** for APEX's *Oracle Text*: a tsvector column or expression (or built from the searchable columns), a text search configuration per application language (`simple` as fallback), `websearch_to_tsquery` for the user's text (phrases, or, -word), the best match first (`ts_rank_cd`) and matched words highlighted (`ts_headline`, escaped); *Did you mean* with `pg_trgm`; SQL Workshop › Table Properties › *Add full-text search* (generated tsvector column and GIN index, previewed, recorded in the Change Log); report search boxes use a tsvector column too; the Advisor warns about a missing GIN index ([full-text search](guide/04-pages-and-regions.md#full-text-search)). (sprint 136) Search type **vector** for APEX's *Oracle Vector Search*: a vector provider embeds the search text, the nearest rows by a `vector(n)` column (cosine, L2 or inner product, a minimum similarity), and **hybrid**: full-text and vector rankings merged by reciprocal rank fusion; as the app's role, so RLS decides what is found; needs pgvector and says so without it; the Advisor checks the provider, the dimensions and the HNSW index ([vector search](guide/04-pages-and-regions.md#vector-search)). No REST data sources or APEX-application search as sources, no custom result templates |
 | URL region | ✅ | (sprint 50) A **url** region frames another site's page (or one of this server) in a sandboxed iframe: the origin is written out (an item can never choose the host), `&ITEM.` values after it are URL-encoded, and the page's CSP gets `frame-src` for exactly the origins of its visible URL regions; height, sandbox flags and full screen in the attributes; an *Open in a new tab* link ([chapter 4](guide/04-pages-and-regions.md#url-url-region)) |
 | Template components and template directives | ✅ | Shared Components → Template components: `#PLACEHOLDERS#` (always escaped), `{if}`, `{case}` and `{loop}` directives, custom attributes, a wrapper; as a region type and as report column templates, with a preview. Templates are checked against an allow-list (no scripts, styles, event handlers or `javascript:` links) ([chapter 4](guide/04-pages-and-regions.md#template-components)) |
 
@@ -213,7 +214,8 @@ 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)). (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 |
+| 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 (sprint 136) A **Retrieve (RAG)** tool type: the model gives a text, the agent gets the best rows of a search configuration (vector or hybrid) as the app's role in a read-only transaction, logged like other tools |
+| Vector providers, `APEX_AI.GET_VECTOR_EMBEDDINGS`, vector search (24.2) | ✅ | (sprint 136, AP-1) Shared Components → **Vector providers** (exported with the application): an AI service with an embedding model (OpenAI `text-embedding-3-*`, Gemini, any OpenAI-compatible endpoint such as Ollama; the key stays with the service) or a SQL / PL/pgSQL function returning `vector`, with its dimensions, checked on every embedding and against vector columns; **Test**. `meta.embed(text, provider)` for function providers in SQL (as the caller; AI services are called by the server only). Workspace utilities → Vector providers: pgvector detected, *Create extension vector* for administrators, the workspace's providers and vector columns. SQL Workshop › Table Properties › **Add vector column**: `vector(n)`, an HNSW index and a trigger that re-embeds changed rows, at once (function) or through a queue the server works in batches within the provider's requests per minute and the app's daily AI limits, logged under AI usage; **Backfill** with progress ([chapter 3](guide/03-builder.md#vector-providers)). No ONNX models in the database (use a function provider, e.g. pgml or pgai) |
 | *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) |
 
@@ -281,7 +283,7 @@ row above where there is one.
 | Automations / scheduler | built in, or `pg_cron` | [chapter 6](guide/06-processing.md#automations), [chapter 15](guide/15-extensions.md#tier-2-third-party-widely-available) |
 | Calling REST APIs synchronously from SQL (`APEX_WEB_SERVICE`; the built-in `meta.web_request()` is queued) | `http`, `pg_net` | [chapter 15](guide/15-extensions.md#tier-3-situational) |
 | Map data | PostGIS | [chapter 15](guide/15-extensions.md#tier-2-third-party-widely-available) |
-| Semantic search / RAG | `pgvector` | [chapter 15](guide/15-extensions.md#tier-2-third-party-widely-available) |
+| Semantic search / RAG | `pgvector` (sprint 136: vector providers, vector and hybrid search and Retrieve tools are built in on it) | [chapter 4](guide/04-pages-and-regions.md#vector-search), [chapter 15](guide/15-extensions.md#tier-2-third-party-widely-available) |
 | Statement auditing | `pgaudit` | [chapter 15](guide/15-extensions.md#tier-2-third-party-widely-available) |
 | Code checks (Advisor for PL/pgSQL functions) | `plpgsql_check` (used by the Advisor when installed) | [chapter 15](guide/15-extensions.md#tier-2-third-party-widely-available) |
 | Pivot reports | `tablefunc` | [chapter 15](guide/15-extensions.md#tier-1-included-with-postgresql) |

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;
@@ -1721,6 +1824,7 @@ scheme (only users who pass it are offered the tool) and one of these types:
 | **REST data source** | a REST data source of the application; the parameters become its parameters | as in [assistant regions](04-pages-and-regions.md#ai_assistant-ai-assistant) |
 | **JavaScript** | nothing on the server: after the answer the browser calls the function registered with `pgkiln.actions.register(action)` (with `{value: arguments}`) and the dynamic actions of the **custom event** of that name (the arguments as JSON) | once, right after the answer; the arguments are escaped data in the page |
 | **Navigate** | the model picks one of the tool's **pages**, a link text and item values of that page; pgkiln builds the URL with the item values' **checksum** (bound to application, page and user) and shows the link under the answer | only pages the user may open are offered (the page's authorization scheme and sign-in); only items of that page; the model's values are never substituted (`&ITEM.`); nothing opens the link by itself |
+| **Retrieve (RAG)** | (sprint 136) the model gives a text (`QUERY`); pgkiln runs the tool's **search configuration** (best: [vector or hybrid](04-pages-and-regions.md#vector-search)) and returns the best rows' title, text (the description column) and score | as the application's role in a **read-only transaction** with the time limit, so row level security decides which rows the model sees; at most *maximum rows* rows (default 5); no parameters of its own |
 
 The model's arguments are checked against the parameters before a tool runs; they are bind values
 (escaped literals), never SQL text, and can't replace the server's own names (`:APP_USER`, `:APP_ID`, …).
@@ -1743,6 +1847,70 @@ earns most?* and it calls the SQL tool `top_earners` as the signed-in user's rol
 *Open BLAKE's record*, a link to the employee form (page 3) with a valid checksum, only to users who
 may open that page.
 
+## Vector providers
+
+(sprint 136; APEX: Vector Providers) A **vector provider** turns a text into an **embedding**: a list of numbers
+(the *dimensions*) whose distance says how close two texts are in meaning. Vector columns, search configurations
+of type [vector or hybrid](04-pages-and-regions.md#vector-search) and the [Retrieve tools](#ai-agents) of AI
+agents use one. Providers are part of the application: Shared Components → Generative AI → **Vector providers**
+(kept in `meta.app.vector_providers`, exported with the application). A provider has:
+
+- a **name** (static ID, upper case, e.g. `DOC_EMBEDDINGS`) and a description;
+- a **type**:
+  - *AI service with an embedding model*: an [AI service](#ai-services) the application may use (OpenAI,
+    Gemini, or OpenAI-compatible such as Ollama; Claude has no embeddings API) and the model, exactly as the
+    provider names it: `text-embedding-3-small` (1536 dimensions; OpenAI shortens them to the provider's
+    dimensions), `text-embedding-3-large` (3072), `gemini-embedding-001`, `nomic-embed-text` (768),
+    `mxbai-embed-large` (1024) … The key, base URL and daily limits are the service's: **the key stays with the
+    AI service** (encrypted, write-only, never exported); the export carries only the service's name. Texts per
+    request and requests per minute limit the background embedding of queued rows;
+  - *SQL or PL/pgSQL function*: `schema.name` of a function `(text)` returning `vector`, `real[]` or
+    `float8[]`, e.g. a model inside the database (`pgml.embed`, `ai.openai_embed` of pgai) or your own;
+- the **dimensions**: every embedding is checked against them, and a vector column is `vector(n)` with this *n*
+  (an HNSW index takes up to 2,000).
+
+**Test** embeds a sample text and shows how many dimensions came back. A provider's page lists the search
+configurations and vector columns that use it. In SQL, `meta.embed(text, 'DOC_EMBEDDINGS')` returns a function
+provider's embedding as `real[]` (cast it: `meta.embed(…)::vector`), running the function **as the role of the
+query** (its grants apply: grant execute on it to the application's role). An AI service is called by the pgkiln
+server, never from SQL: `meta.embed` says so for such a provider; use it through a search configuration, a
+Retrieve tool or a vector column's queue.
+
+**pgvector.** Everything with vectors needs the [pgvector](https://github.com/pgvector/pgvector) extension in
+the database (pgkiln itself installs without it). Workspace utilities → **Vector providers** says whether it is
+installed; when the database server has the package, administrators get **Create extension vector** (pgvector is
+not a trusted extension: the owner connection must be a superuser; otherwise a superuser runs
+`create extension vector;`). Without the package: install it (`apt install postgresql-17-pgvector`, the
+`pgvector/pgvector:pg17` Docker image, or the managed database's *vector* extension). The same page lists every
+provider of the workspace's applications and the vector columns they keep current.
+
+**Add vector column** (SQL Workshop › Table Properties, or a table's ⋯ menu) needs a table with a one-column
+primary key: pick a provider of the workspace's applications, the **source columns** (their text, one per line,
+is embedded), the distance (`cosine`, `l2`, `inner_product`) and the column's and index's names. **Preview DDL**
+shows what Apply runs in one transaction (recorded in the Change Log); **Open in the worksheet** puts it there:
+
+```sql
+alter table sales.doc add column embedding public.vector(1536);
+create index doc_embedding_idx on sales.doc using hnsw (embedding vector_cosine_ops);
+create trigger embedding_embed after insert or update of title, body on sales.doc
+  for each row execute function meta.embedding_enqueue('12', 'DOC_EMBEDDINGS', 'embedding', 'id', 'title', 'body');
+```
+
+**Keeping it current.** With an AI service the trigger (`meta.embedding_enqueue`) puts the changed row's key in a
+queue (`meta.embedding_queue`; a change to other columns, or to the same text, queues nothing). The server embeds
+queued rows in batches of the provider's *texts per request*, at most its *requests per minute*, within the
+application's daily AI limits, logged under AI usage (source *embedding*), and writes the vectors with the
+workspace's developer connection (the one the SQL Workshop uses). A failing batch keeps its message and is tried
+again after 1, 2, 4 … minutes (six times). A function provider can instead set the embedding **in the trigger**
+(`meta.embedding_set`, before insert or update, as the role that writes the row). After Apply the rows already
+there are queued; the page shows each vector column with a progress bar (rows embedded, queued, failing, the last
+message) and **Backfill**, which queues the rows without an embedding (or, ticked, all rows: after changing the
+provider's model). The server polls the queue every `EMBEDDING_INTERVAL_S` seconds (default 5);
+`EMBEDDINGS=off` keeps a server from embedding (another one does it).
+
+**What goes to the provider**: the source columns' text of every row, and every search text. Choose a provider
+your organisation allows for that data; a function provider keeps it in the database.
+
 ## App Builder AI
 
 The App Builder uses one AI service (APEX: AI Assistant in App Builder and SQL Workshop). An
@@ -1860,6 +2028,10 @@ the SQL Workshop's connection may use. Without JavaScript the header's field ope
     **Apply** runs both in one transaction and records them in the **Change Log**; **Open in the worksheet** puts them
     there. The column keeps itself up to date; adding it rewrites the table. Name the column in a search
     configuration of search type *fulltext*, or in a report's `fulltext` attribute.
+    (sprint 136) **Add vector column…** (Table Properties, or the ⋯ menu): an embedding column `vector(n)` from a
+    [vector provider](#vector-providers), an HNSW index for the distance and a trigger that re-embeds a row when its
+    source columns change (at once with a function provider, else through the server's queue); the page shows each
+    vector column's progress and **Backfill**. Without pgvector it says what is missing.
   - (sprint 119) **Security** (the Object Browser's *Security* button on a table, *Security…* in its ⋯ menu): the
     table's row level security policies, a matrix of database roles × columns with *read* and *update*, and masked
     columns per application role in a masking view; Preview SQL, Apply (one transaction, recorded in the Change Log)