pgkiln 0.50.0 → 0.52.0

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

@@ -256,7 +256,7 @@ Features for end users:
     computed columns and views under a name, and switch between saved reports (below);
   - **rows per page**, **download CSV / Excel / PDF**, **print**, **reset**.
 - Active search, filters, break, aggregates, highlights, computed columns and views appear as
-  removable chips. Once a group by, pivot or chart is set, **Report / Group by / Pivot / Chart**
+  removable chips (with *Ask in your own words*, as chips with Edit and Remove under the question box). Once a group by, pivot or chart is set, **Report / Group by / Pivot / Chart**
   links switch between the views; all views use the same search, filters and facets.
 - **Paging** with Previous/Next.
 - On phones every row **reflows** into a card with labelled values.
@@ -267,26 +267,71 @@ and highlight values become literals, columns must exist in the result, operator
 functions, chart types and colors come from fixed lists, sort positions are integers, and computed
 column expressions are parsed (below), never pasted into SQL.
 
-### Natural-language filters (*Ask in your own words*)
-
-With an [AI service](06-processing.md#generate-text-with-ai), an interactive report can take a
-question in the user's own words (APEX: natural language to interactive report): *"analysts and
-managers hired before 1982, highest salary first"*. Set `"ai_filter": {"service": "NAME"}` in the
-report's attributes (or *Ask in your own words (AI)* under the report's settings in the page
-designer); a question box appears above the report when the application may use the service.
-
-The question goes to the service with the report's shown columns (names, headings and kinds:
-text, number, date) and its filter operators; the answer is a structured output (filters, a search
-text, a sort column) that pgkiln checks again (only those columns and operators, at most five
-filters, short values) and turns into the report's ordinary URL parameters. So the model can only
-set what the user could set by hand in the Actions menu; the report builds the SQL (values as
-escaped literals) and runs it as the application's role, and the user sees which filters were
-applied and can change or remove them. Hidden columns (`hidden`) are not offered. Signed-in users
-only, unless `"public": true`; logged in the AI usage log with the source `nl2ir`.
+### Ask in your own words (AI interactive reports)
+
+An interactive report can take a request in the user's own words (APEX 26.1/26.2: AI interactive
+reports): *"sum of salary by department where job is clerk"*, *"managers hired before 1982, highest
+salary first"*, *"bonus is 10% of salary"*. Set `"ai_filter": {}` in the report's attributes (or
+*Ask in your own words* under the report's settings in the page designer); a question box appears
+above the report.
+
+The answer is never SQL: it becomes the report's **own settings**, the same ones the Actions menu
+sets: filters, highlights, a search, a sort, a control break, totals (aggregates), a group by, a
+pivot, a chart and computed columns. They are listed under the box as **chips**; each chip has
+**Edit** (a small form with its column, operator, value, function, color or expression) and
+**Remove**, and **Undo** returns to the settings before the last change (the last five steps, kept
+in the session). A new request refines the current settings: a filter on a column replaces that
+column's filters, a sort, break, group by, pivot or chart replaces the old one, highlights, totals
+and computed columns are added; *"start over"* clears them. The chips are buttons of one form, so
+they work without JavaScript.
+
+**Without an AI service** pgkiln reads the request itself with a rule-based parser for common
+phrases (APEX 26.2: works with zero AI). Columns are recognised by name or heading (also without
+spaces, and verbs such as *hired* for `hiredate`); values such as *"only clerks"* or *"in sales"*
+are looked up among the report's own rows (as a query parameter); what isn't understood is said
+in the message, not guessed. Phrases it understands, in English (always), Dutch and German (when
+that is the user's language):
+
+| Request | Becomes |
+|---|---|
+| *salary over 3000*, *salary between 1,000 and 3k*, *hired before june 1981*, *hired in 1981*, *name contains "mi"*, *no commission* | filters (`gt`, `ge` + `le`, `lt`, a date range, `contains`, `null`) |
+| *only clerks*, *not clerks*, *in sales*, *active* | a filter on the column that holds the value |
+| *sort by hire date, newest first*, *highest salary first* | the sort |
+| *sum of salary by department*, *count by department and job* | a group by with its function |
+| *total salary*, *average salary* | a totals row |
+| *break by department* | a control break |
+| *pivot sum of salary by department and job* | a pivot |
+| *pie chart of count by department*, *chart of salary by job* | a chart |
+| *highlight salary over 4000 in red* | a highlight |
+| *bonus is 10% of salary*, *yearly = sal * 12* | a computed column |
+| *search for smith* | the search |
+| *start over*, *clear all* | no settings |
+
+Dutch (*salaris boven 3000*, *sorteer op datum aflopend*, *som van salaris per afdeling*, *alleen
+klerken*, *bonus is 10% van salaris*) and German (*Gehalt über 3000*, *sortiere nach Datum
+absteigend*, *Summe von Gehalt pro Abteilung*, *nur Angestellte*) work the same way; another
+language adds a phrase table to `src/runtime/ir-phrases.ts`.
+
+**With an AI service** (`"ai_filter": {"service": "NAME"}`, an [AI
+service](06-processing.md#generate-text-with-ai) the application may use), the request goes to the
+service with the report's shown columns (names, headings and kinds: text, number, date, boolean),
+its operators and functions and the current settings; the answer is a structured output. When the
+service is disabled or not allowed for the application, the built-in phrases answer instead. The
+request and the column names go to the service's provider; logged in the AI usage log with the
+source `nl2ir`.
+
+Either way the answer is checked again before it is applied: only the report's shown columns
+(`hidden` columns are neither offered nor accepted), operators, functions, chart types and colors
+from the report's fixed lists, at most five filters, highlights and totals, short values (which
+become escaped literals or query parameters), and computed expressions that pass the same
+validator as Actions → Compute (below). A chip edit is checked the same way; a form that names a
+hidden column, an unknown operator or a chip that isn't there is refused. The report builds the
+SQL and runs it as the application's role. Signed-in users only, unless `"public": true`.
 
 | Key | Meaning |
 |---|---|
-| `ai_filter.service` | The AI service's name |
+| `ai_filter` | `{}` for the built-in phrases |
+| `ai_filter.service` | An AI service's name (the built-in phrases when it isn't available) |
 | `ai_filter.placeholder` | The question box's placeholder |
 | `ai_filter.public` | Also for users who are not signed in |
 
@@ -1186,9 +1231,12 @@ Attributes (written by the region's **Settings**):
 
 | Key | Default | Meaning |
 |---|---|---|
-| `sources` | | `[{"id": "orders", "label": "Orders", "description": "…", "schema": "sales", "table": "order_v", "columns": [{"name": "total", "label": "Total", "format": "FML999G990D00"}]}]` |
+| `sources` | | `[{"id": "orders", "label": "Orders", "description": "…", "schema": "sales", "table": "order_v", "columns": [{"name": "total", "label": "Total", "format": "FML999G990D00"}]}]`; (sprint 110) or a dataset: `{"id": "sales", "dataset": "sales"}` (label and description optional) |
 | `sharing` | `true` | `false`: reports stay private |
 | `share_authz` | | An authorization scheme: only users that pass it may share reports |
+| `edit_authz` | | (sprint 110) An authorization scheme: only users that pass it build, change, save and delete reports; the others only run shared ones |
+| `admin_authz` | | (sprint 110) An authorization scheme: users that pass it unpublish and delete anyone's reports |
+| `publishing` | `false` | (sprint 110) `true`: shared reports are *published*: a stable URL, Publish / Unpublish buttons, pins |
 | `page_size` | `25` | Rows per page of a detail report (5 to 200) |
 | `welcome` | `true` | `false`: the compact start (a list of sources and *Start*) instead of the welcome page |
 | `welcome_title`, `welcome_text` | | The welcome page's greeting instead of pgkiln's (translated like other application texts) |
@@ -1200,6 +1248,27 @@ region when an application is replaced. The HR example's page 36 (*My reports*)
 (a view without the user name and photo columns) and leave requests (row level security: an
 employee sees only their own), with King's shared report *Salary by department*.
 
+#### Datasets and reporting applications
+
+(sprint 110) A source may be a **dataset** of the workspace ([App Builder → Data
+Reporter](03-builder.md#data-reporter-datasets-and-reporting-applications)): tables and views of one schema with
+their joins, the offered columns with labels, format masks and descriptions (shown under the column in the editor),
+and a row filter. The region's Settings add one under *Add a data source → Or a dataset of the workspace*. The
+runtime reads the dataset when the page is drawn and builds its SELECT from the definition (identifiers quoted,
+values escaped literals, operators from the whitelist), and the report runs on it as a subquery, as the
+application's database role. A dataset that was deleted disappears from the region; a column that no longer exists
+makes the report show an error.
+
+With **`publishing`**, shared reports are *published*: an editor saves a report privately and **Publishes** it
+(or ticks *Publish for all users* when saving), and **Unpublishes** it again. A published report has a **stable
+URL**, `/a/<alias>/reports/<id>`, shown on the report: it opens the report on its page (signing in first), so it
+can be bookmarked or sent. Every signed-in user may **Pin** a published report: pinned reports come first on the
+welcome page (a [preference](06-processing.md) of the user, `reporter.pins.<region>`). Users that don't pass
+`edit_authz` see only the published reports: no *New report* cards, no editor (report parameters in the URL are
+ignored), no saving. Users that pass `admin_authz` unpublish and delete anyone's reports. The HR example's dataset
+`hr` (`examples/hr/hr_63_datasets.sql`: employees with their department, active ones only) is the one a reporting
+application is made from in the guide's chapter 3.
+
 ### `form_designer` (Form Designer)
 
 A **Form Designer** region (sprint 85; pgkiln's own, APEX has no counterpart) lets the application's
@@ -1273,8 +1342,12 @@ forms *Departments* and *Book a meeting*.
 ### `ai_assistant` (AI assistant)
 
 An **AI assistant** region (APEX: AI Assistant, AI agents and tools) is a chat with an
-[AI service](06-processing.md#generate-text-with-ai) (Claude or OpenAI) that an administrator
-configured and allowed for the application. The developer gives it a system prompt and, optionally,
+[AI service](06-processing.md#generate-text-with-ai) (Claude, OpenAI, Gemini or an OpenAI-compatible
+endpoint) that an administrator configured and allowed for the application. Either the region names an
+**[AI agent](03-builder.md#ai-agents)** of the application (`"agent": "SALES_AGENT"`: the agent sets the
+service, system prompt, reasoning effort, tools, steps and output limit, and its authorization scheme
+decides who may use the region; tools may also be PL/pgSQL functions, JavaScript actions and links to
+pages), or the developer gives the region a system prompt and, optionally,
 **context queries** and **tools**; the model then answers questions about the application's data,
 calling the tools when it needs to, like an agent. It works without JavaScript (the message is
 posted and the page comes back with the answer); with JavaScript the Send button shows that the
@@ -1320,6 +1393,7 @@ Attributes (written by the region's **Settings**; they travel with the applicati
 
 | Key | Default | Meaning |
 |---|---|---|
+| `agent` | | (121) An [AI agent](03-builder.md#ai-agents) of the application; then leave out `service`, `system`, `tools` and `max_rounds` |
 | `service` | | The AI service's name |
 | `system` | | The system prompt (`&ITEM.` substitutions as delimited data) |
 | `welcome` | | The first message shown (translatable) |
@@ -1333,7 +1407,7 @@ Attributes (written by the region's **Settings**; they travel with the applicati
 
 The HR example's page 38 (*HR assistant*) has an assistant with a context query over `hr.policy`
 and four tools (the user's own leave, colleagues, departments, and *request_leave*, which files a
-leave request), next to a staff list with [*Ask in your own words*](#natural-language-filters-ask-in-your-own-words).
+leave request), next to a staff list with [*Ask in your own words*](#ask-in-your-own-words-ai-interactive-reports).
 
 ### Template components
 

package/docs/guide/05-items.md

@@ -217,6 +217,11 @@ item's config. A combobox is free text and isn't checked.
 A `popup_lov` item shows the chosen value's display text and a **Search** button. The button
 opens a dialog with a search field: the server searches the item's own list of values (case
 insensitive, on the display column and any extra columns) and answers one page at a time.
+**The next page loads as the list scrolls** (APEX: infinite scrolling): when the end of the list
+comes into view the dialog fetches the next `page_size` rows and adds them, until the list of
+values has no more, so a list of thousands of rows scrolls to its end without a *More* button. A
+new search starts over at the first page. A browser without `IntersectionObserver` pages with
+‹ and *More* instead.
 
 - **Several columns**: the first column is the display value, the second the return value, and
   any further columns are shown in the dialog (and searched), for example:
@@ -233,7 +238,8 @@ insensitive, on the display column and any extra columns) and answers one page a
   parameter (never SQL text), only for an item the user may see and change on a page they may
   open. A submitted value must be one the list of values returns, or the page shows an error.
 
-The HR example's page 26 (*Pick an employee*) has one with name, job and department columns.
+The HR example's page 26 (*Pick an employee*) has one with name, job and department columns;
+page 47 (*Component details*) one over 6,000 rows, 100 a page.
 
 ## Cascading lists of values
 

package/docs/guide/06-processing.md

@@ -28,13 +28,14 @@ simply closes the dialog.
 ### Menu buttons and badges
 
 A button with action `menu` opens a dropdown (an HTML `<details>` element, so it works without
-JavaScript). `menu` is a JSON array of at most 20 entries; each is either a **link** to a page of
-the application or a **submit request**:
+JavaScript). `menu` is a JSON array of at most 20 entries; each is a **link** to a page of
+the application, a **submit request** or an **action** that runs dynamic actions:
 
 ```json
 [{"label": "Leave requests", "page": 6, "icon": "list"},
  {"label": "Details", "page": 3, "items": {"P3_EMPNO": "&P22_EMPNO."}},
- {"label": "Start over", "request": "RESET", "confirm": "Clear the form?", "authz": "ADMIN"}]
+ {"label": "Start over", "request": "RESET", "confirm": "Clear the form?", "authz": "ADMIN"},
+ {"label": "Export", "action": "EXPORT", "icon": "download"}]
 ```
 
 | Key | Meaning |
@@ -42,6 +43,7 @@ the application or a **submit request**:
 | `label` | The entry's text (1–100 characters) |
 | `page`, `items` | A link: the page and the items to set (signed with a checksum, like any link) |
 | `request` | A submit: the page is submitted with this request, as if a button of that name was pressed. Validations, processes and branches with `when_button` see it |
+| `action` | Runs the [dynamic actions of event `menu_entry`](07-dynamic-actions.md#menu-entry-chosen) with this name (capitals, digits and `_`) as trigger (APEX: Menu entry chosen) |
 | `confirm` | A confirmation question first |
 | `authz` | The entry only exists for users who pass this authorization scheme |
 | `icon` | An [icon](09-reference.md#icons) name |
@@ -852,6 +854,9 @@ application ask someone to approve, reject or complete something, and act on the
 | When overdue, Maximum renewals, Escalation role | The expiration policy ([below](#overdue-tasks-expire-renew-escalate)); empty: overdue tasks stay open |
 | Details page, Details item | The subject links to this page, setting the item to the record key |
 | On completion (SQL) | Runs as the application's role when the task is approved, rejected or completed (below) |
+| Outcomes | Custom outcomes instead of Approve / Reject ([below](#custom-outcomes)) |
+| Events, When the completion SQL fails | Actions when a task is completed, expires or its completion SQL fails ([below](#task-events-and-notifications)) |
+| Notifications | E-mail templates pgkiln sends when a task is created, completed or expires |
 
 **2. Application SQL creates tasks**, for example in the process that saves a request or in a
 trigger:
@@ -903,6 +908,62 @@ When a record is decided somewhere else (for example with buttons on its own pag
 open tasks so they don't linger: `select meta.close_tasks('EXPENSE_APPROVAL', :P5_ID::text,
 'approved')` (no completion SQL runs).
 
+<a id="custom-outcomes"></a>**Custom outcomes** (APEX 26.2: task outcomes). A task definition may list its own outcomes
+instead of Approve / Reject (or Complete):
+
+```json
+[{"name": "YES", "label": "Yes", "colour": "success"},
+ {"name": "NO", "label": "No", "colour": "danger"},
+ {"name": "UNDECIDED", "label": "Undecided", "colour": "warning"}]
+```
+
+The task list then shows one button per outcome, with its label and colour (`default`, `primary`, `success`,
+`danger` or `warning`: a fixed list, so a definition can't add other classes). The outcome is stored in lower case
+(`meta.tasks.outcome = 'yes'`), `:OUTCOME` in the completion SQL is the name (`YES`), and the history shows the label.
+A task ends only with an outcome of its definition: `meta.complete_task` refuses any other (also Approve / Reject
+on a definition with its own outcomes), and so does `meta.close_tasks(name, detail_pk, outcome)`. A
+[workflow](#workflows) branches on them in a task step's `next` (`{"yes": "PAY", "no": "END"}`) or a switch case
+`{"outcome": "UNDECIDED", "next": "ASK_AGAIN"}`. Names are letters, digits and underscores (at most 30, at most 10
+outcomes); `cancelled`, `expired` and `default` are reserved.
+
+<a id="task-events-and-notifications"></a>**Task events and notifications** (APEX 26.2: Human Task events). A
+definition's *Events* are actions on what happens to its tasks:
+
+```json
+[{"on": "complete", "type": "sql", "code": "select expenses.log_decision(:DETAIL_PK::int, :OUTCOME, :APPROVER)"},
+ {"on": "expire", "type": "mail", "to": "select email from staff where role = 'manager'", "template": "TASK_EXPIRED"},
+ {"on": "fail", "type": "workflow", "workflow": "FIX_REQUEST", "vars": {"REASON": "&ERROR."}}]
+```
+
+| `on` | When |
+|---|---|
+| `complete` | The task was completed, with any outcome (also by `meta.close_tasks` with an outcome) |
+| `expire` | The task expired ([below](#overdue-tasks-expire-renew-escalate)) |
+| `fail` | The definition's completion SQL raised an error |
+
+| `type` | Does | Fields |
+|---|---|---|
+| `sql` | Runs statements as the application's role | `code` |
+| `mail` | Queues an e-mail through [`meta.send_mail_template`](#e-mail-templates) or [`meta.send_mail`](#sending-e-mail) | `to` (a SELECT returning addresses, or addresses with `&NAME.`), `template`, or `subject` and `body` with `#NAME#` placeholders |
+| `workflow` | Starts a workflow with the task's record key and parameters | `workflow`, `vars` (variable → text, `&NAME.` allowed) |
+
+Binds (and `#NAME#` placeholders): the task's parameters, `:TASK_ID`, `:DETAIL_PK`, `:SUBJECT`, `:OUTCOME`,
+`:APPROVER`, `:INITIATOR`, `:EVENT`, and for `fail` `:ERROR` and `:COMMENT`. *Complete* and *expire* events run
+right after the commit: a trigger queues them (`meta.task_hook`, closed to applications) and the server runs each
+in a transaction of its own, as the application's role with the person who completed the task (or the initiator) as
+`meta.app_user()` and the task's tenant; one that fails is tried three times and keeps its error on the
+`meta.task_hook` row. *Fail* events run in the request that completed the task: the completion SQL's effect is
+undone, the failure is in the task's history, the actions run, and **When the completion SQL fails** says what
+happens to the task: `reopen` (the default) undoes the decision so the task stays open, `complete` keeps it completed
+without the SQL's effect. The user sees the error either way. Without fail events or a recovery, an error undoes the
+decision as before.
+
+**Notifications** are e-mails pgkiln sends itself, from the application's
+[e-mail templates](#e-mail-templates): `{"create": "TASK_CREATED", "complete": "TASK_DONE", "expire": "TASK_EXPIRED"}`.
+*create* goes to the potential owners (the named users, the actual owner and the application's users with one of
+the owner roles), *complete* to the initiator, *expire* to both, at the e-mail address of their account. The
+placeholders are those of the events. They need a mail service, like `meta.send_mail`.
+
 #### Overdue tasks: expire, renew, escalate
 
 A task definition with *Due in* can say what happens to a task that is still open after its due date (APEX:
@@ -930,9 +991,9 @@ workflow whose task is cancelled.
 | `meta.task_events` | View: the history and comments of those tasks |
 
 The task tables themselves are closed to the application's role: rights are checked by these
-functions and views, for every call. To tell owners by e-mail, call
-[`meta.send_mail`](#sending-e-mail) from the task definition's SQL or from an automation that
-reminds owners of overdue tasks; or put a task list on the home page.
+functions and views, for every call. To tell owners by e-mail, use the definition's
+[notifications](#task-events-and-notifications), call [`meta.send_mail`](#sending-e-mail) from the task
+definition's SQL or from an automation that reminds owners of overdue tasks; or put a task list on the home page.
 
 **Example:** in the HR sample application, a leave request creates a `LEAVE_APPROVAL` task for the
 employee's manager; *My tasks* (page 14) approves or rejects it through `hr.decide_leave`, the same
@@ -954,9 +1015,15 @@ steps; the builder checks them and draws the flow.
 | `invoke_api` | Calls a REST data source or a URL on the server; values of the response become variables ([below](#invoke-api-steps)) | `source` + `params`, or `url`, `method`, `credential`, `body`; `variables`, `status_variable`, `response_variable`, `timeout`, `next` |
 | `parallel` | Starts a branch at each of its steps; they run side by side | `branches` (the first step of each, at least two), `join` |
 | `join` | Where the branches of a `parallel` step meet | `wait_for` (`all`, the default, or `any`), `next` |
+| `send_mail` | Queues an e-mail ([below](#send-e-mail-steps)) | `to`, `template` (or `subject` and `body`), `cc`, `next` |
+| `draft` | A placeholder while modelling: only in a development version ([below](#draft-steps)) | `note`, `next` |
 | `end` | Ends the workflow | |
 
 `next` is optional: the following step in the list (after the last one, the workflow is complete).
+A task step's `next` per outcome names the outcomes of its task definition, [custom ones](#custom-outcomes) too,
+plus `cancelled`, `expired` and `default`. A `switch` case is either `{"when": "SQL condition", "next": …}` or
+`{"outcome": "YES", "next": …}`, which compares the outcome of the last task (`:TASK_OUTCOME`); the builder checks
+that a task of the workflow can end with it.
 
 ```json
 [{"name": "CHECK",    "type": "switch", "cases": [{"when": ":AMOUNT::numeric > 1000", "next": "DIRECTOR"}], "otherwise": "MANAGER"},
@@ -976,7 +1043,7 @@ select meta.start_workflow('EXPENSE', :P5_ID, jsonb_build_object('AMOUNT', :P5_A
 
 The variables (upper case) are binds in every step, with `:DETAIL_PK`, `:WORKFLOW_ID` and
 `:INITIATOR`; after a task step also `:TASK_OUTCOME` (`APPROVED`, `REJECTED`, `COMPLETED`,
-`CANCELLED`) and `:TASK_APPROVER`. The title may use `&VAR.`.
+`CANCELLED`, `EXPIRED` or a custom outcome such as `YES`) and `:TASK_APPROVER`. The title may use `&VAR.`.
 
 **How it runs.** The pgkiln server runs workflows: right after they start or a task of theirs
 ends (`NOTIFY`), and it checks for waits that are over every few seconds (`WORKFLOW_INTERVAL_S`,
@@ -1008,6 +1075,29 @@ background runs with the tenant of the session that queued it. Filter your own t
 (`where tenant_id = meta.tenant_id()`, or a row level security policy). Use row level security in
 the tenant's tables as well: the tenant is a value the application sets, not a database boundary.
 
+### Send e-mail steps
+
+A `send_mail` step (APEX 26.1: the *Send E-Mail* activity) queues an e-mail through the application's mail service,
+as the application's role, like [`meta.send_mail`](#sending-e-mail) in a `sql` step:
+
+```json
+{"name": "TELL", "type": "send_mail", "to": "select email from staff where id = :DETAIL_PK::int", "template": "REQUEST_DONE"}
+{"name": "NOTE", "type": "send_mail", "to": "desk@example.com, &MANAGER_EMAIL.", "subject": "Request #TITLE# done", "body": "Decided by #TASK_APPROVER#."}
+```
+
+`to` is a SELECT returning addresses, or addresses with `&VAR.` substitutions; `cc` likewise addresses. With a
+`template` ([e-mail templates](#e-mail-templates)), or a `subject` and a plain-text `body`, the placeholders `#NAME#`
+are the variables, `DETAIL_PK`, `WORKFLOW_ID` and `INITIATOR`. No recipient: the step goes on (the history says
+so). A mail that can't be queued (no mail service, an address that isn't one, the daily limit) faults the step.
+The history records the mail's id; it is sent after the step's transaction commits.
+
+<a id="draft-steps"></a>**Draft steps** (APEX 26.2: Draft activities). A step of type `draft` stands for something
+not modelled yet (`{"name": "BUDGET_CHECK", "type": "draft", "note": "check the budget", "next": "APPROVE"}`).
+It may be in a development version only: the builder shows a warning and doesn't offer **Activate** while a version
+has one, `meta.activate_workflow_version` refuses it, and the database refuses draft steps in a definition's active
+steps (so a new definition can't have them either: create it, then a new version to model with drafts). The diagram
+draws them dashed. An instance can never reach one; if it did (steps changed with SQL), the step faults.
+
 ### Invoke API steps
 
 An `invoke_api` step (APEX: the *Invoke API* activity) calls a web service: a
@@ -1086,6 +1176,28 @@ steps with problems), and the active one becomes inactive. **Discard** throws a
 away. The Versions table shows each version with its instance count and diagram; the Instances
 table shows which version each instance runs and where it is.
 
+<a id="migrating-instances"></a>**Migrating running instances** (APEX 26.2: in-flight workflow migration). Running
+instances (active, waiting or faulted) of an older version can move to a newer one: the active version or an inactive
+version activated after theirs. Under the definition, **Migrate instances…** (shown
+while there are such instances) opens a page where you choose the version and the instances, and map each step an
+instance is at to a step of the new version (a step of the same name is proposed). **Preview** shows per instance
+where it goes or why it can't; **Migrate** then moves them all in one transaction, with their variables, the task
+they wait for and their wait, logged in each instance's history (*migrated*, `version 1 → 2: APPROVE → APPROVE
+(by admin)`) and in `meta.workflow_migration`. Nothing moves when one of them can't:
+
+- a step without a mapping, or mapped to a step the version doesn't have (or a draft);
+- an instance waiting for a task must go to a task step that creates a task of the same definition;
+  one at a `wait` step to a `wait` step (its wait goes on), one at a join to a join;
+- an instance inside parallel branches, or calling a web service at that moment: try again later.
+
+The database function is `meta.migrate_workflows(definition_id, version, ids, mapping, apply, by)` (the owner's,
+for the builder and scripts; not for applications).
+
+<a id="diagram-export"></a>**The diagram as a file.** Under the diagram, **Download SVG** downloads the whole model
+of the version shown (`/builder/apps/<app>/shared/workflow_definition/<id>/diagram.svg?v=<version>`), a standalone
+SVG with its own colours; **Download PNG** draws that SVG in the browser (with JavaScript; without it the SVG link
+remains). Step names and labels are escaped, so a definition can't put markup into the file.
+
 **The console.** A region of type **`workflows`** lists the workflows the user started (or, with
 `"context": "admin"`, those they administer), with their state, the version, the current steps (several with parallel branches), a diagram
 and the history. The initiator and administrators can **terminate** a workflow (its open tasks and
@@ -1102,7 +1214,10 @@ branches are cancelled); administrators can retry a faulted one.
 created. Its version 2 (part 18) prepares the workplace (the manager's task) and, in a parallel
 branch, the access that employees with a salary of 2500 or more need (a switch and an
 administrator's task); when both branches are done, the manager is notified (SQL). Version 1, which
-did this one after the other, is inactive. *My tasks* (page 14) shows the workflows. Part 34 adds
+did this one after the other, is inactive. *My tasks* (page 14) shows the workflows. Part 67 adds `SALARY_CHANGE`: a
+`SALARY_DECISION` task with the outcomes Yes, No and Undecided (the owners get the `SALARY_TASK` e-mail, a complete
+event notifies the initiator), a switch on the outcome (Undecided asks again), SQL that applies the salary and, in
+version 2, a `send_mail` step to the employee; version 3 is in development with a draft step. Part 34 adds
 `DEPARTMENT_CHECK`, started by *Check in a workflow* on page 23: an `invoke_api` step reads the
 department from the example's own REST API (the `DEPARTMENT` source of part 23, so the server must
 allow `127.0.0.1:3100`), a `switch` on `HTTP_STATUS`, and SQL that notifies the initiator.

package/docs/guide/07-dynamic-actions.md

@@ -37,6 +37,7 @@ your own from a static application file.
 | `selection_change` | Rows are selected in a report with [row selection](04-pages-and-regions.md#row-selection), or another master row in a grid; the condition sees the selected values, colon separated | Region ids or static ids |
 | `before_submit` | The page is about to be submitted; a declined `confirm` keeps the page | – |
 | `custom` | JavaScript raised the event: `pgkiln.trigger('ORDER_SAVED', value)` (APEX: custom events, `apex.event.trigger`) | Event names (case-insensitive) |
+| `menu_entry` | An entry `{"label": …, "action": "NAME"}` of a [menu button](06-processing.md#menu-buttons-and-badges) was chosen (APEX: Menu entry chosen); the condition sees the entry's name ([below](#menu-entry-chosen)) | Entry names, or menu button names (any of their entries) |
 
 **The actions of one event and trigger run one after the other, in sequence order** (APEX: the true
 actions of a dynamic action), each waiting for the one before (a server action for its answer). A
@@ -79,11 +80,44 @@ actions of a dynamic action), each waiting for the one before (a server action f
 | `print` | browser | The browser's print dialog |
 | `current_position` | browser | The device's position as `latitude,longitude` (5 decimals) into the first affected item |
 | `share` | browser | The device's share sheet with the page's title, `message` and address; where there is none, the address is copied |
+| `wait_popup` | browser | Shows a modal "please wait" popup with `message` (default *Please wait…*) until `remove_wait_popup` or the next page (APEX: Show Wait Popup); [below](#wait-popup) |
+| `remove_wait_popup` | browser | Removes the wait popup (APEX: Remove Wait Popup) |
 
 Server-side actions first store `items_to_submit` in session state, run as the application's
 database role like everything else, and check the page's and the dynamic action's authorization.
 The SQL itself never reaches the browser.
 
+## Wait popup
+
+`wait_popup` covers the page with a small dialog (a spinner and `message`) while something slow
+runs, so the user doesn't click twice; `remove_wait_popup` takes it away. Because the actions of
+one event run in sequence, each waiting for the one before, two patterns cover most cases:
+
+| Sequence | Event | Action | |
+|---|---|---|---|
+| 10 | `click` on `RECALC` (a submit button) | `wait_popup` | *Recalculating…*: the popup stays until the next page arrives |
+| 10 | `click` on `CHECK` | `wait_popup` | *Checking…* |
+| 20 | `click` on `CHECK` | `execute_sql` | the Ajax call (also `set_value`, `refresh_region`, `download`, a plug-in) |
+| 30 | `click` on `CHECK` | `remove_wait_popup` | |
+
+`before_submit` → `wait_popup` shows it for every submit of the page. A submit the browser refuses
+(a required field is empty) removes it again, and so does going back to the page in the browser.
+The popup is a modal `<dialog>`: the page below can't be clicked or focused, Escape doesn't close
+it, its text is a status message that screen readers read out, and the page's `<main>` is
+`aria-busy` while it shows. It follows the theme (light and dark) and needs no inline styles or
+scripts. From JavaScript: `const done = pgkiln.waitPopup('Saving…'); … done();` (or
+`pgkiln.removeWaitPopup()`).
+
+## Menu entry chosen
+
+A [menu button](06-processing.md#menu-buttons-and-badges)'s entry can run dynamic actions instead
+of linking or submitting: `{"label": "Export", "action": "EXPORT"}`. Dynamic actions with event
+`menu_entry` and trigger `EXPORT` run when it is chosen (the menu closes first); a trigger with the
+menu button's name runs for every action entry of that menu, and a client-side condition tests the
+entry's name (`equals` `EXPORT`). Without JavaScript such an entry does nothing, like a button with
+action `da`. The HR example's page 47 has an *Actions* menu whose *Count employees* entry shows a
+wait popup around an Ajax call.
+
 ## Ajax callbacks
 
 A page process with point **ajax** (APEX: an On Demand process) runs only when JavaScript calls it by

package/docs/guide/09-reference.md

@@ -481,9 +481,10 @@ navigation entries and application processes have the same `build_option` column
 | `push_key` | The VAPID key pair of an application with [push notifications](17-mobile.md#push-notifications): `public_key`, `private_key` (encrypted with `PGKILN_SECRET_KEY`). Not exported | no |
 | `push_subscription` | Devices with notifications on: `app_id`, `username`, `endpoint` (the push service URL), the device's keys `p256dh` and `auth`, `user_agent`, `created_at`, `last_sent_at`, `failures`. Not exported | no (through `meta.has_push_subscription`) |
 | `push_message` | [Push notifications from SQL](#push-notifications-from-sql): `app_id`, `username`, `title`, `body`, `url`, `tag`, `urgency`, `ttl_s`, `status`, `attempts`, `devices`, `delivered`, `message`, `requested_by`, times. Kept 7 days, not exported | no |
-| `ai_service` | [AI services](06-processing.md#generate-text-with-ai) of the installation: `name`, `provider` (`anthropic`, `openai`), `model`, `effort`, `refusal_fallback`, `max_tokens`, `timeout_s`, `base_url`, `api_key_enc` (encrypted with `PGKILN_SECRET_KEY`, write-only), `enabled`. Not exported | no |
+| `ai_service` | [AI services](06-processing.md#generate-text-with-ai) of the installation: `name`, `provider` (`anthropic`, `openai`, `gemini`, `openai_compatible`: 121), `model`, `effort`, `refusal_fallback`, `max_tokens`, `timeout_s`, `base_url`, `api_key_enc` (encrypted with `PGKILN_SECRET_KEY`, write-only), `enabled`. Not exported | no |
 | `app_ai_service` | Which applications may use which AI service, with daily limits `max_requests` and `max_tokens` (null: no limit). Not exported | no (through `meta.ai_available`) |
 | `ai_usage` | One row per AI request: `at`, `app_id`, `page_no`, `username`, `service`, `provider`, `model`, `source`, `input_tokens`, `output_tokens`, `duration_ms`, `status`, `message` (an error class, never prompt or answer text). Not exported | no |
+| `ai_tool_call` | (121) Every tool call of an [AI assistant or agent](03-builder.md#ai-agents): `at`, `app_id`, `page_no`, `region_id`, `username`, `agent`, `tool`, `type`, `arguments` (the model's, cut to 4 KB), `status` (`ok`, `error`, `refused`), `duration_ms`, `message`. Kept 30 days, not exported | no |
 | `ai_conversation` | [AI assistant](04-pages-and-regions.md#ai_assistant-ai-assistant) conversations: one per session and region (`messages`: the provider's history, `turns`: what the page shows); deleted with the session. Not exported | no |
 | `ai_table_note` | Descriptions of tables and columns for models ([App Builder AI](03-builder.md#app-builder-ai)): `schema_name`, `table_name`, `column_name` (`''` for the table), `note`. Installation data, not exported | no |
 | `blueprint` | Saved [blueprints](03-builder.md#creating-an-application-from-a-blueprint): `name`, `spec` (the JSON), `app_id` (the application last created from it), `created_by`. Builder data, not exported | no |

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

@@ -22,10 +22,11 @@ What's missing is listed in the [feature parity matrix](../apex-feature-parity.m
 | Instance administration: install/upgrade log | Workspace utilities → Installation (administrators) |
 | `APEX_WEB_SERVICE.make_rest_request`, `g_status_code` | `meta.web_request(url, method, body, headers, credential)` or `meta.web_request_source(source, params)`, then `meta.web_response(id)`. **Asynchronous**: the server makes the request after the page process that queued it, or after the commit ([chapter 9](09-reference.md#web-requests-from-sql)) |
 | Workspace → Generative AI services; *Generate Text with AI* process and dynamic action; `APEX_AI.generate` | Workspace utilities → AI services (Claude or OpenAI; administrators); the `ai_generate` process and dynamic action, with structured outputs into items ([chapter 6](06-processing.md#generate-text-with-ai)); `meta.ai_generate(service, prompt, system, schema)` then `meta.ai_result(id)` ([chapter 9](09-reference.md#ai-requests-from-sql)) |
-| AI Assistant region; AI agents with tools; natural language to interactive report (NL2IR) | The `ai_assistant` region: a chat with context queries (RAG over your queries) and tools (SQL as the app role with bound arguments, REST data sources) ([chapter 4](04-pages-and-regions.md#ai_assistant-ai-assistant)); `"ai_filter"` on a report: *Ask in your own words* ([chapter 4](04-pages-and-regions.md#natural-language-filters-ask-in-your-own-words)) |
+| AI Assistant region; AI agents with tools; AI interactive reports (natural language to interactive report) | The `ai_assistant` region: a chat with context queries (RAG over your queries) and tools (SQL as the app role with bound arguments, REST data sources) ([chapter 4](04-pages-and-regions.md#ai_assistant-ai-assistant)); `"ai_filter"` on a report: *Ask in your own words*, the request becomes the report's settings as editable chips, with or without an AI service ([chapter 4](04-pages-and-regions.md#ask-in-your-own-words-ai-interactive-reports)) |
 | App Builder / SQL Workshop AI Assistant (create pages, generate and explain SQL); describing tables for AI | The App Builder's AI service: *Create pages with AI* (proposals you confirm), SQL Workshop → AI (SQL from a question, shown not run; explain a query or error), *Describe tables* (`meta.ai_table_note`, optionally `COMMENT ON`) ([chapter 3](03-builder.md#app-builder-ai)) |
 | Blueprints (spec-driven development) | Create → From a blueprint: a JSON blueprint (tables, pages, menu, sample data), optionally drafted by AI, reviewed, then created in one transaction ([chapter 3](03-builder.md#creating-an-application-from-a-blueprint)) |
 | `APEX_DATA_PARSER.parse`, `get_columns` | `meta.parse_data(blob, …)` (rows with `cols` and `data`), `meta.parse_data_columns(blob, …)`; CSV/TSV and JSON, not Excel or XML ([chapter 9](09-reference.md#parsing-files-in-sql)) |
+| Team Development (issues, labels, milestones, templates, feedback) | Builder → Team Development (`/builder/team`): issues per workspace with labels in groups, milestones, assignees, application and page links, Markdown comments with @mentions shown in the builder, history, saved views and a board; a set-up wizard with sample labels, templates and milestones; feedback and developer comments become issues. No e-mail and no GitHub synchronisation ([chapter 3](03-builder.md#team-development)) |
 | Workspace users (APEX accounts), Application Access Control | `meta.account` (Builder → Users), `meta.app_access` (Access control) |
 | Page access protection "Arguments must have checksum" | `protection = 'checksum'` (the default) |
 | Automatic row processing (DML) | Process type `form_dml` |