pgkiln 0.51.0 → 0.52.0

package/docs/guide/01-installation.md

@@ -182,6 +182,8 @@ which is read at startup; real environment variables take precedence.
 | `PDF_FONT`, `PDF_FONT_BOLD` | *(none)* | TrueType fonts for report PDFs, for text beyond Western European (e.g. `DejaVuSans.ttf`) |
 | `ANTHROPIC_API_KEY` | *(none)* | Default API key of [AI services](03-builder.md#ai-services) with the provider Claude that have no key of their own |
 | `OPENAI_API_KEY` | *(none)* | Default API key of AI services with the provider OpenAI that have no key of their own |
+| `GEMINI_API_KEY` | *(none)* | (sprint 111) Default API key of AI services with the provider Gemini that have no key of their own |
+| `OPENAI_COMPATIBLE_API_KEY` | *(none)* | (sprint 111) Default API key of OpenAI-compatible AI services (Ollama, vLLM, Azure OpenAI) that have no key of their own; without either, no key is sent (`none`) |
 | `PGKILN_SECRET_KEY` | *(none)* | Encrypts the secrets of web credentials and the API keys of AI services; at least 32 characters (e.g. `openssl rand -base64 32`). Keep it outside the database; changing it means entering the secrets again ([chapter 19](19-rest-data-sources.md)) |
 | `PGKILN_REST_ALLOWED_HOSTS` | *(none: no outgoing calls)* | Hosts REST data sources and `invoke_api` may call: `api.example.com`, `*.example.com`, `host:8443`, `*` (any public host) ([chapter 19](19-rest-data-sources.md#server-configuration-and-the-allow-list)) |
 | `PGKILN_REST_PRIVATE_HOSTS` | *(none)* | Hosts that may resolve to private, loopback or link-local addresses (also allows them) |
@@ -264,9 +266,11 @@ stops the container at once with a message saying so.
 | `PGKILN_IMAGE` | `pgkiln/pgkiln:latest` | The image to run, e.g. a fixed version (`pgkiln/pgkiln:0.31.0`) or `ghcr.io/pgkiln/pgkiln` |
 
 **Upgrading:** with the published image: `docker compose pull`, then `docker compose up -d` (with a
-fixed version in `PGKILN_IMAGE`, change it first). Built from a checkout: `git pull`, then
-`docker compose up -d --build`. The new container migrates the database
-before it starts serving. Back up first (`docker compose exec db pg_dump -U pgkiln pgkiln > backup.sql`).
+fixed version in `PGKILN_IMAGE`, change it first); `up -d` replaces the container when the image changed, so
+`--force-recreate` isn't needed. Built from a checkout: `git pull`, then `docker compose up -d --build`. The new
+container migrates the database before it starts serving. A `compose.yaml` from pgkiln 0.51.0 or older has
+`pull_policy: missing` under `pgkiln`, which makes `docker compose pull` skip an image that is already present:
+delete that line (or take the current `deploy/compose.yaml`) before the first upgrade this way. Back up first (`docker compose exec db pg_dump -U pgkiln pgkiln > backup.sql`).
 Keep `PGKILN_SECRET_KEY`: without it, stored secrets (web credentials, AI keys, push keys) can't be decrypted.
 
 ## Upgrading

package/docs/guide/03-builder.md

@@ -158,6 +158,7 @@ applications' files. Choose what goes in:
 | REST source catalogs | Every [catalog](19-rest-data-sources.md#rest-source-catalogs) with its services |
 | SQL scripts, blueprints, data generators | The SQL Workshop's saved work |
 | Data Reporter datasets | Every [dataset](#data-reporter-datasets-and-reporting-applications) (sprint 110) |
+| Team Development | [Label groups, labels, milestones, templates and issues](#team-development) with their comments and history; an issue's application by alias (sprint 113) |
 
 Never in the file: the workspace's name, its [isolation](#isolated-workspaces) and database roles, passwords and
 secrets, script runs and other history. **Applications are exported on their own** (an application's *Export*).
@@ -275,7 +276,8 @@ JavaScript. The [default-password banner](#signing-in-and-developer-accounts) st
 - **System message**: the pgkiln version the server runs and, when the [release check](#the-release-check) is on and
   a newer release is out, **pgkiln X is available** with a link to its release notes and how to upgrade (back up,
   install the new version, `pgkiln migrate`, restart).
-- **A side column**: About, **Learn more** (this guide, the [tutorial](10-tutorial.md),
+- **A side column**: About, **Team Development** ([open issues](#team-development), those assigned to you, unseen
+  mentions of you, or *Set up Team Development* before it is set up), **Learn more** (this guide, the [tutorial](10-tutorial.md),
   [Coming from APEX](11-from-apex.md), the changelog and the discussions on GitHub) and Resources.
 
 ### The release check
@@ -753,6 +755,10 @@ author or an administrator deletes it. The page list counts each page's comments
 another number keeps its lock and comments. Locks and comments belong to this installation and
 are not exported.
 
+**Make an issue** under a comment turns it into a [Team Development](#team-development) issue about the same page;
+the comment then links to its issue. A page with open issues shows them above the designer's tabs (*1 open issue:
+…*, with *New issue* for that page), and the application's page list tags such pages (*2 issues*).
+
 ### Arranging the layout
 
 Regions are placed in sequence order; a region's *column span* (1–12) sets its width, and a
@@ -840,7 +846,7 @@ out, other keys are kept, columns the query no longer returns stay listed so you
 | `smart_filters` | The same per-column facets, the suggestions per facet and the search field's placeholder |
 | `display_selector` | Tabs or a select list, "Show all", remember the choice; per other region of the page: in a tab and the tab name (saved in that region's settings) |
 | `ai_assistant` | The AI service (those the application may use), system prompt, welcome text, placeholder, error message, tool rounds per question, questions per conversation, public or not, and the context queries and tools as JSON (checked when saving: query shapes, parameter types, REST data sources and authorization schemes that exist) ([AI assistant](04-pages-and-regions.md#ai_assistant-ai-assistant)) |
-| `report` (also) | *Ask in your own words (AI)*: the AI service and placeholder of the [natural-language filters](04-pages-and-regions.md#natural-language-filters-ask-in-your-own-words) |
+| `report` (also) | *Ask in your own words (AI)*: off, the built-in phrases or an AI service, and the placeholder of [Ask in your own words](04-pages-and-regions.md#ask-in-your-own-words-ai-interactive-reports) |
 | `data_reporter` | Data sources (a table or view each: static id, label, description, offered columns with labels and format masks; or (sprint 110) a dataset of the workspace), who may share, build and moderate reports, publishing, rows per page ([Data Reporter](04-pages-and-regions.md#data_reporter-data-reporter)) |
 | `form_designer` | Who may design forms (an authorization scheme), data sources (a table or view each: static id, label, description, key column, may add / change / delete rows, offered columns with labels and lists of values), rows per page ([Form Designer](04-pages-and-regions.md#form_designer-form-designer)) |
 
@@ -958,6 +964,48 @@ user, page, rating and browser), set its status (*Open*, *In progress*, *Done*,
 an answer the user sees. Answering is allowed while the application is locked or Run only. The
 setting travels with the export; the feedback itself belongs to the installation.
 
+**Make an issue** turns an entry into a [Team Development](#team-development) issue of the application's workspace
+(title from its first line, the feedback quoted, linked to its page, labelled *Bug* for a problem and *Feature* for
+an idea when the workspace has those labels); open feedback becomes *In progress*, and the entry links to its issue.
+
+## Team Development
+
+(sprint 113, migration 122; APEX: Team Development) An issue tracker for the developers of a
+[workspace](#workspaces): **Team Development** on the icon rail (`/builder/team`) and a block in the
+[Workspace home](#workspace-home)'s side column with the number of open issues. Everything is of the current
+workspace and works without JavaScript.
+
+- **Set up** installs sample data, like APEX's set-up wizard: the label groups *Type* (Bug, Feature, Task) and
+  *Priority* (High, Medium, Low), issue templates (*Bug report*, *Feature request*, *Task*), canned responses and the
+  milestones *1.0*, *1.1* and *Backlog*. What the workspace has already (by name) is kept, so it can run again.
+  The samples are in English; other languages are added in `src/team-samples.ts`.
+- **Issues** have a title, a description in Markdown (rendered safely: raw HTML is shown as text, links are http,
+  https, mailto or relative), *Open* or *Closed*, labels, a milestone, assignees (the workspace's developers and the
+  installation's administrators), and optionally an application of the workspace and one of its pages. Comments are
+  Markdown too; *Comment and close* does both. **@name** mentions a developer of the workspace: they see it under
+  *Mentions of you* (and on the Workspace home) until they open the issue or mark them seen; no mail is sent. Every
+  change is in the issue's history (who changed the title, labels, milestone, assignees, link or status, and when).
+  An issue is deleted by its author or a workspace administrator.
+- **The list** filters by status, label, milestone, assignee (*Me*, *Nobody*), application and a search of the title
+  and text (or `#12` for issue 12). **Save view** keeps the filters under a name, for you only.
+- **The board** shows the issues as columns of cards, by the labels of one label group (a card moved to *High*
+  loses *Medium*; *None of these* removes the group's labels) or by milestone. Each card has a *Move* form, so it
+  works without dragging.
+- **Labels** belong to label groups and have a colour from a fixed palette (red, orange, yellow, green, teal, blue,
+  purple, gray). **Milestones** have a due date and are open or closed, with the share of their issues closed.
+  **Templates** are issue templates (title, labels, text: *Start from a template* on *New issue*) and canned
+  responses (*Canned response* → *Insert* above an issue's comment field). Any developer of the workspace adds and
+  changes them; only its administrators delete labels, label groups and milestones.
+- Issues come from [feedback](#feedback) and [developer comments](#page-locks-and-comments) with **Make an issue**,
+  linked both ways. The page designer shows a page's open issues and App Home counts them per page (*Open issues* in
+  its Tasks).
+
+Issues and the rest are workspace data: they are not part of an application's export (an in-place import keeps them)
+but travel in the workspace's [Export and import](#export-and-import) (*Team Development*): labels, milestones and
+templates match by name, an issue by its title and creation time; assignees are kept when they are developers of the
+importing workspace and the application link when it has an application with that alias. GitHub synchronisation is
+not part of it.
+
 ## Working copies
 
 APEX's working copies: a second application to change in isolation, then merge back. On an
@@ -1024,8 +1072,8 @@ is the earlier page: every component in one rail, with **Access control** next t
 | **Shortcuts** | Named texts: `"NAME"` in static content, help texts and confirm messages ([chapter 2](02-concepts.md#shortcuts-name)) |
 | **Application computations** | Computations of (application) items for every page: at sign-in, before every page, after every submit ([chapter 6](06-processing.md#application-computations)) |
 | **REST modules** | REST endpoints (method, path, SQL) served by pgkiln, with an OpenAPI description ([chapter 13](13-rest-api.md#rest-modules-in-the-builder)) |
-| **Workflows** | Multi-step processes of tasks, SQL, web service calls (invoke API), decisions, waits and parallel branches, with versions and a diagram ([chapter 6](06-processing.md#workflows)) |
-| **Task definitions** | Approvals and action tasks: subject, owners, administrators, due date, the SQL that runs on completion ([chapter 6](06-processing.md#approvals-and-the-task-list)) |
+| **Workflows** | Multi-step processes of tasks, SQL, web service calls (invoke API), e-mail, decisions, waits and parallel branches, with versions, draft steps, migration of running instances and a diagram (SVG / PNG download) ([chapter 6](06-processing.md#workflows)) |
+| **Task definitions** | Approvals and action tasks: subject, owners, administrators, due date, custom outcomes, the SQL that runs on completion, events and e-mail notifications ([chapter 6](06-processing.md#approvals-and-the-task-list)) |
 | **Document templates** | Letters, invoices and other PDFs filled from a query ([chapter 16](16-files.md#document-templates)), with a preview |
 | **Build options** | Include / exclude switches for features; pages and their components name one in their *Build option* property, and *Used in* lists them ([chapter 6](06-processing.md#build-options)) |
 | **Web credentials** | How the application signs in to web services (basic, API key header, bearer token, OAuth2 client credentials); the secret is write-only and encrypted ([chapter 19](19-rest-data-sources.md#web-credentials)) |
@@ -1293,7 +1341,12 @@ Workspace utilities → **AI services** (administrators only; APEX: *Generative
 large language model services of this installation. A service has:
 
 - a **name** (upper case, e.g. `CLAUDE`) by which processes, dynamic actions and SQL refer to it;
-- a **provider**: *Claude (Anthropic)* or *OpenAI*, called through their official SDKs;
+- a **provider**: *Claude (Anthropic)* or *OpenAI*, called through their official SDKs; *Gemini*
+  (Google, through its OpenAI-compatible endpoint `https://generativelanguage.googleapis.com/v1beta/openai/`,
+  with the `openai` SDK); or *OpenAI-compatible*: any endpoint that speaks OpenAI's Chat Completions,
+  such as Ollama (`http://localhost:11434/v1`), vLLM, Azure OpenAI (`https://<resource>.openai.azure.com/openai/v1/`)
+  or a gateway. An OpenAI-compatible service needs a base URL; its key may stay empty for endpoints
+  without keys (a local Ollama);
 - a **model**, exactly as the provider names it (new Claude services start with `claude-opus-5-5`);
   pgkiln never changes or downgrades it;
 - for Claude, the **effort** (how deeply the model thinks; current Claude models always think, lower
@@ -1305,8 +1358,9 @@ large language model services of this installation. A service has:
 - an optional **base URL** for a gateway or proxy that speaks the provider's API (calls to the AI
   service don't go through `PGKILN_REST_ALLOWED_HOSTS`: only administrators set this URL);
 - the **API key**: stored encrypted with `PGKILN_SECRET_KEY`, write-only (never shown again, never
-  exported or logged, not readable by applications). Without one the server's `ANTHROPIC_API_KEY` /
-  `OPENAI_API_KEY` is used.
+  exported or logged, not readable by applications, never sent to the browser). Without one the
+  server's `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY` or `OPENAI_COMPATIBLE_API_KEY`
+  (by provider) is used.
 
 On a service's page, **Applications** sets which applications may use it, each with optional daily
 limits (requests and input + output tokens per UTC day; a request over a limit fails with a message
@@ -1314,11 +1368,71 @@ and is logged as *limited*), and **Test** sends a prompt (logged as a builder te
 on the list page for all services, the usage log: the last requests and the totals per application
 and service of the last 30 days.
 
+An interactive report's *Ask in your own words* doesn't need a service: without one (or when the
+service is disabled or not allowed for the application) pgkiln reads the request with its built-in
+phrases ([chapter 4](04-pages-and-regions.md#ask-in-your-own-words-ai-interactive-reports)).
+
 **Prompts go to the provider.** Whatever a prompt contains, including the item values substituted
 into it, is sent to the chosen provider (or the gateway of the base URL). Choose providers and
 models that your organisation allows for that data. See
 [Generate text with AI](06-processing.md#generate-text-with-ai).
 
+## AI agents
+
+Shared Components → Generative AI → **AI Agents** (APEX 26.1 / 26.2: AI Agents and AI Tools) holds an
+application's agents and the tools they may use. An agent reasons over a user's request in an
+[AI assistant region](04-pages-and-regions.md#ai_assistant-ai-assistant) and acts **only through the
+tools you approve**; pgkiln prepares the context, runs each tool call itself under the checks below,
+and composes the conversation.
+
+An **agent** has:
+
+- a **name** (upper case, e.g. `SALES_AGENT`) that regions refer to, and a description;
+- an **AI service** the application may use, and a **system prompt** (`&ITEM.` is replaced by the item's
+  value as delimited data, as in assistant regions);
+- a **reasoning effort**: *low*, *medium* or *high*, or empty for the service's own. For Claude it is
+  the output effort (thinking depth, `output_config.effort`); for OpenAI, Gemini and OpenAI-compatible
+  services it is sent as `reasoning_effort` (leave it empty for models without reasoning: they refuse it);
+- the **tools** it may use (ticked from the application's tools);
+- **maximum steps** (rounds of tool calls per question, 1–20, default 5) and **maximum output tokens**
+  per call (never above the service's maximum);
+- an **authorization scheme**: other users see *You may not use this assistant* instead of the message
+  box, and their questions are refused before anything is sent to the AI service.
+
+A **tool** has a name the model calls it by, a description that tells the model what it does and when
+to use it, optional **parameters** (JSON: `{"DNAME": {"type": "string", "description": "…", "optional": true}}`;
+types string, integer, number, boolean, date, `enum` for a list of texts), an optional authorization
+scheme (only users who pass it are offered the tool) and one of these types:
+
+| Type | What runs | Checks |
+|---|---|---|
+| **SQL query** | one `SELECT` (or `WITH`, `VALUES`, `TABLE`) with the parameters as `:NAME` bind values, plus `:APP_USER` and items | as the application's database role (grants and row level security apply), in a **read-only transaction** (functions it calls can't write either), with a time limit (1–60 s, default 15) and at most *maximum rows* rows (default 50) back to the model |
+| **PL/pgSQL function** | `schema.function` called with named arguments: each parameter name in lower case is an argument name (`P_EMPNO` → `p_empno => …`) | as the application's role; it **may change data** (committed); same time limit and rows |
+| **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 |
+
+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`, …).
+Tool results go back to the model as data, with the instruction never to follow instructions inside them.
+
+**Every tool call is logged** with the arguments the model gave, its status (*ok*, *error*, or *refused*
+for a page the user may not open) and duration: in the page's debug messages (level 4) and under
+Activity → **AI usage** → *Tool calls* (`meta.ai_tool_call`, kept 30 days; arguments may hold user data,
+only developers see them). The token usage of each call to the model is logged as before.
+
+Agents and tools are kept in the application (`meta.app.ai_agents`, `meta.app.ai_tools`) and **exported
+with it**; an export made before they existed imports with none. The forms check each one before
+saving (a SQL tool must be a query, a function `schema.name`, a navigate tool's pages must exist); the
+runtime checks them again and shows *This assistant is not set up yet* for a broken one. Renaming a
+tool keeps it in its agents; a tool an agent uses can't be deleted; renaming an agent renames it in
+the regions that use it.
+
+The HR example (`examples/hr/hr_64_ai_agent.sql`) has an agent `HR_AGENT` on page 46: ask *Who in Sales
+earns most?* and it calls the SQL tool `top_earners` as the signed-in user's role, then offers
+*Open BLAKE's record*, a link to the employee form (page 3) with a valid checksum, only to users who
+may open that page.
+
 ## App Builder AI
 
 The App Builder uses one AI service (APEX: AI Assistant in App Builder and SQL Workshop). An

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 |
 
@@ -1297,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
@@ -1344,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) |
@@ -1357,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.