pgkiln 0.51.0 → 0.53.0

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 |
@@ -779,7 +781,12 @@ Microsoft retires basic authentication (a password) for SMTP in Exchange Online:
 or the Graph provider. Secrets are stored encrypted with `PGKILN_SECRET_KEY`, are write-only in the
 builder, never exported and never readable by applications. Each service lists the **From
 addresses** it may send as (an address, or `@example.com` for a whole domain); an administrator
-chooses each application's service, its From address and an optional **limit per day**.
+chooses each application's service, its From address and an optional **limit per day**. A
+workspace's administrators can also set up the [workspace's own mail
+service](03-builder.md#a-workspaces-own-mail-service) (sprint 118): the workspace's applications that
+an administrator gave no service send through it, with its default From address. Administration →
+[Mail queue](03-builder.md#mail-queue) shows the delivery per hour and per application, the slowest
+provider calls and the failures with the provider's answer, with Retry and Purge.
 
 **How mail is sent.** `meta.send_mail` and the others only *queue* the mail, in the caller's
 transaction: a transaction that rolls back sends nothing. After the commit, the server sends it at
@@ -852,6 +859,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 +913,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 +996,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 +1020,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 +1048,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 +1080,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 +1181,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 +1219,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/08-security.md

@@ -540,6 +540,61 @@ quoted with `escapeIdentifier`, every value is checked (dates, numbers, schema n
 The page is for administrators only (others get 403), every change needs the CSRF token, and pgkiln's own roles can't
 be changed, dropped or granted from it, so the page can't take pgkiln's own connections away.
 
+## Data security per table: rows, columns and values
+
+(sprint 119) PostgreSQL has row level security but no column masking, so pgkiln puts a table's security in three
+layers, all ordinary database objects, and shows them on one page: **SQL Workshop → Object Browser → a table →
+Security** (also *Security…* in the table's ⋯ menu). It is pgkiln's answer to APEX 26.2's Deep Data Security.
+
+- **Rows**: the table's row level security policies (above), listed with a link to Table Properties to switch row
+  level security on and to *Add policy*.
+- **Columns**: a matrix of **database roles × columns** with *read* and *update* per cell. The rows are the roles
+  that have privileges on the table and the database roles of the workspace's applications (with the applications
+  that run as them). Apply writes `GRANT` / `REVOKE SELECT (c, …)` and `UPDATE (c, …)`. A column a role may not read
+  is refused by PostgreSQL ("permission denied") whoever sends the query. The table's owner, superusers and roles that
+  bypass row level security are listed apart: column privileges can't restrict them.
+- **Values**: masked columns per **application role** (`meta.has_role()` of the signed-in user). A column's mask is
+  *empty (null)*, `***` or `***` plus the last four characters; tick the application roles that see the real value,
+  and *Everyone else* for users with none of the listed roles. The masks live in a **masking view** next to the table
+  (default name `<table>_masked`):
+
+  ```sql
+  create view sales.orders_masked with (security_barrier) as
+  select t.id, t.customer,
+         case when (select meta.has_role('manager')) then t.amount end as amount,
+         case when false then t.iban::text else '***' || right(t.iban::text, 4) end as iban
+    from sales.orders t;
+  ```
+
+  The view is owned by a role per schema, `<schema>_masking` (nologin), which pgkiln creates the first time. That
+  role is no owner, superuser or role that bypasses row level security (Apply checks it), so the table's policies
+  still apply inside the view; and it is a member of the database roles that read the table, so policies written
+  `to <role>` apply as well. The configuration is kept in the view's comment, so it travels with `pg_dump`,
+  Generate DDL and the change log; there is no `meta` table for it.
+
+**Preview SQL** shows the statements, **Apply** runs them in one transaction (and records a change set in the
+Change Log), **Open in the worksheet** puts them there. Nothing is changed when one statement fails.
+
+**The mask holds only where the view is read.** As long as a role may still read the raw column on the table, its
+queries on the table see the value; the preview warns about each such column. Point the application's pages,
+REST handlers and AI tools at the view, then untick *read* of the masked columns for the role, and the value is
+masked everywhere that role connects.
+
+Every client meets the same rules because they all run as the application's database role with the same identity:
+
+| Client | Runs as | `meta.app_user()` / `meta.has_role()` from |
+|---|---|---|
+| Pages, processes, dynamic actions, AI assistant and AI agent tools | the application's role (`appTx`) | the session |
+| REST module handlers, AutoREST | the application's role | the bearer token (its user, the user's roles) |
+| The MCP server's `run_query` with `alias` (and `user`) | the application's role | the user's roles in the application ([chapter 20](20-ai-agents.md#safety)) |
+| psql, other tools | whatever role they log in as | — (only grants and policies apply) |
+
+Policies and masks that use `meta.has_role()` can be combined: with a policy that shows a manager the rows of their
+department, and `amount` masked for everyone but `manager`, a clerk reads their own rows with an empty amount.
+Policies written per database role (`to sales_app`) apply to the masking role for every role it is a member of, so
+prefer policies on `meta.app_user()` / `meta.has_role()` on tables with a masking view. The HR example's page 48
+*Salaries (masked)* reads `hr.emp_masked` (`examples/hr/hr_70_data_security.sql`).
+
 ## Session state protection
 
 - **URL items**: on pages with protection *Arguments must have checksum* (the default), item

package/docs/guide/09-reference.md

@@ -81,7 +81,9 @@ select meta.web_request_source('EXCHANGE', '{"currency": "EUR"}');
   must be on `PGKILN_REST_ALLOWED_HOSTS` (unset: no calls), private and loopback addresses are refused
   when the connection is made unless the host is in `PGKILN_REST_PRIVATE_HOSTS`, redirects (at most 3)
   go through the same checks, the response is cut off at `PGKILN_REST_MAX_BYTES` (default 5 MB) and
-  the time limit is 1–60 seconds.
+  the time limit is 1–60 seconds. A workspace's [network access list](03-builder.md#network-access)
+  (sprint 118) narrows the hosts for its applications: a refused request ends with `status` `error`
+  and the reason in `message`, and is logged (debug log, Refused calls).
 - **Web credentials** are named, never passed: `p_credential => 'NAME'` signs the request with a
   credential of the current application (basic, bearer, header, OAuth2), and only for the URLs it is
   valid for. The secret is decrypted by the server for the request only and is never stored with it
@@ -481,9 +483,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` |
@@ -64,6 +65,7 @@ What's missing is listed in the [feature parity matrix](../apex-feature-parity.m
 | Automatic Time Zone | Settings → Globalization → Time zone and Automatic time zone; My account → Time zone ([chapter 14](14-globalization.md#time-zones)) |
 | Universal Theme's default style (26.1: *Iris*) | Base style *Iris* (the default for new applications), *Lavender* or *Standard* ([chapter 14](14-globalization.md#base-styles-iris-lavender-and-standard)) |
 | Theme styles, *Enable End Users to Choose Theme Style* | Theme style (automatic/light/dark) and *Users may choose light or dark*; Theme Roller style variants with *Users may choose a style* ([chapter 14](14-globalization.md#style-variants-theme-roller)) |
+| Universal Theme 26.2: *Pillar Light* / *Pillar Dark*, Theme Roller's *Header Pillar Strip*, `u-color-*-subtle` | Theme Roller → *Navigation appearance* and *Header strip colour* (per application or style), the same utility classes ([chapter 14](14-globalization.md#navigation-appearances-pillar-light-and-pillar-dark)) |
 | Template Options (regions, buttons) | *Template options* in the Page Designer: CSS classes from a fixed list ([chapter 4](04-pages-and-regions.md#template-options)) |
 | ORDS | Not needed to serve apps; REST APIs with PostgREST, see [below](#ords-and-postgrest) |
 | Export `f123.sql` / APEXlang | `meta.export_app('alias')` (JSON) |