pgkiln 0.51.0 → 0.53.0

package/docs/guide/03-builder.md

@@ -158,9 +158,11 @@ 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*).
+Never in the file: the workspace's name, its [isolation](#isolated-workspaces) and database roles, its
+[mail service](#a-workspaces-own-mail-service) and [network access list](#network-access) (installation-specific, like
+isolation), passwords and secrets, script runs and other history. **Applications are exported on their own** (an application's *Export*).
 
 **Import** reads such a file into the current workspace, for the components you choose. Components with a name the
 workspace already has are kept, or replaced with *Replace components with the same name*; nothing is deleted. A
@@ -275,7 +277,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
@@ -300,9 +303,16 @@ The App Builder's home page, `/builder/apps` (`/builder` shows it too, unless th
   developers, the SQL Workshop, and for administrators [workspaces](#workspaces), AI services and the
   [installation log](#installation)). The list, the dashboard and Recent show the current workspace.
 - **The applications**, as a report (application id, name, alias, pages, page views of the last 24
-  hours, sign-in, last updated, and Edit / Run) or as cards. **Search** filters the list as you type
+  hours, sign-in, last updated, **updated by**, **working copies**, and Edit / Run) or as cards. **Search** filters the list as you type
   (by name, alias or id; without JavaScript, press Enter). Click a column heading, or use
   **Actions**, to sort. The view and the sort are remembered until you sign out.
+- (sprint 116) **Updated by** is the developer who changed the application last in the builder (any change to its
+  pages, shared components or settings; locks and comments don't count) or who created, imported or copied it;
+  *Updated* is the later of that change and the application's own settings. An import with `pgkiln import` or the
+  MCP server changes *Updated* only. **Working copies** counts the application's [working copies](#working-copies)
+  and links to them. A **lock icon** after the name shows that the application is [locked](#page-locks-and-comments),
+  with its owner in the tooltip (and for screen readers). The cards show the same as small badges. On phones the
+  report keeps the id, the name with the lock and the actions.
 - **A side column** (on the right on wide screens, below the list otherwise): About, **Recent** (the
   applications you opened last) and Tasks.
 - **The workspace message**, when the workspace has one, above the tiles.
@@ -753,6 +763,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 +854,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 +972,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 +1080,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)) |
@@ -1287,13 +1343,79 @@ provider grant it the application permission *Mail.Send*; for SMTP with OAuth2 t
 *SMTP.SendAsApp* and register its service principal in Exchange Online. In both cases limit it to the
 sending mailboxes (an application access policy or RBAC for Applications).
 
+
+### Mail queue
+
+Administration menu → **Mail queue** (`/builder/mail-queue`; APEX 26.2: Administration → Mail queue): the delivery
+health of the mail queue, for administrators (every workspace, or one) and a workspace's administrators (the current
+workspace's applications only; other developers get 403). Filter by period (24 hours, 48 hours, 7 days), workspace and
+application:
+
+- **figures**: queued now, retrying now (failed with an error that may pass, waiting for the next of its 5 attempts),
+  being sent, sent and failed in the period, the share delivered and the average provider call;
+- **Per hour**: queued, sent, failed and retrying mail per hour (UTC);
+- **Slowest provider calls**: the 10 longest hand-overs of the period (how long the provider took to accept or refuse
+  the mail), with application, service and outcome;
+- **Per workspace and application**: sent, failed, retrying and queued mail, the average and slowest call;
+- **Failures**: every failed mail (kept 30 days) with the provider's answer, e.g. the SMTP server's
+  `550 5.1.1 no such user`. **Retry** queues one again with fresh attempts, **Purge** deletes it; *Retry all failed*
+  and *Purge all failed* act on the failures of the filter (never outside the developer's scope).
+
+Bodies and attachments are never shown here. Every action checks again on the server that the mail's application is in
+the developer's scope, and is written to the activity log.
+
+### A workspace's own mail service
+
+A workspace's page → *Mail and network access* → **mail service** (`/builder/workspaces/<id>/mail`; APEX 26.1:
+workspace-level SMTP credentials), for the workspace's administrators: a mail service of the workspace's own, with the
+same providers and checks as [above](#mail-services). The applications of the workspace that an administrator gave no
+service send through it (an application an administrator gave one keeps it; a service of another workspace is never
+used). Its secret is stored encrypted with `PGKILN_SECRET_KEY` like a web credential's: write-only, never shown, never
+exported. It differs from an installation service in two ways that keep it from reaching what the installation
+doesn't allow:
+
+- it uses the provider's own API: no API base URL and no token URL (OAuth2 goes to Microsoft Entra of the tenant);
+- an SMTP server must be on the installation's allow-list (`PGKILN_REST_ALLOWED_HOSTS`, e.g. `smtp.example.com:587`)
+  and the workspace's [network access](#network-access) list, and resolve to a public address (unless
+  `PGKILN_REST_PRIVATE_HOSTS` lists it). The server resolves the host once and connects to the address it checked,
+  with the host name kept for TLS, on every send and test.
+
+### Network access
+
+Administration menu → **Network access** (`/builder/network`; APEX 26.2: workspace network ACLs), for administrators
+(any workspace, `?ws=`) and a workspace's administrators (their workspaces): which web services a workspace's
+applications may call. The installation's list (`PGKILN_REST_ALLOWED_HOSTS`, set in the server's environment, shown
+read-only; the private hosts to administrators only) applies to every workspace. A workspace can choose **Only the
+hosts below**: then every outgoing call made for one of its applications must match one of its entries *and* the
+installation's list. A workspace's list only narrows; it can never widen the installation's, and private, loopback and
+link-local addresses stay refused unless the installation allows them. Entries are `api.example.com`, `*.example.com`
+(its subdomains) or `api.example.com:8443` (that port only); restricted with no entries means no outgoing calls.
+
+It is enforced on the server for every outgoing web call of the workspace: `meta.web_request` and
+`meta.web_request_source`, REST data sources (regions, write-back, synchronisation, the assistant), the Invoke API
+process and workflow step, web credential token endpoints, object storage of file items, the builder's *Test* of a
+source, REST source catalogs read from a URL, and the SMTP server of the workspace's own mail service. Every redirect
+hop is checked again, and a REST source's cached response is not served once its host is off the list. A refused call
+fails with *The host … is not on the network access list of workspace …*, is written to the application's debug log
+(level 2, warning, for `meta.web_request` in a page process; level 1 for regions and processes) and appears under
+**Refused calls** (kept 7 days). **Check a URL** says whether a URL may be called, without calling it.
+
+Not covered by a workspace's list: the installation's own services, which only administrators configure (installation
+mail services, AI services, the geocoder, sign-in providers) and push notification services (their own list,
+`PGKILN_PUSH_HOSTS`).
+
 ## AI services
 
 Workspace utilities → **AI services** (administrators only; APEX: *Generative AI services*) lists the
 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 +1427,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 +1437,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
@@ -1429,6 +1612,10 @@ the SQL Workshop's connection may use. Without JavaScript the header's field ope
     transaction (nothing changes when one fails, and the error shows under *Output*); **Open in the worksheet** puts
     them there instead. *Use as template* starts a new table with the same columns and keys (names with `_copy`).
     Defaults, checks and index expressions are single expressions (no `;` or comments).
+  - (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)
+    or Open in the worksheet ([chapter 8](08-security.md#data-security-per-table-rows-columns-and-values)).
   - **Run Statement** (**Ctrl/Cmd + Enter**) runs the statement at the cursor: the one the cursor is in, else the
     nearest one before it. A selection runs as it is, even when it holds several statements. The rows of the last
     query show in **Query Result**, up to 500, with row numbers, numbers right-aligned and NULL as *(null)*. The

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