pgkiln 0.50.0 → 0.52.0

package/docs/guide/12-development.md

@@ -21,6 +21,9 @@ src/
   env.ts                   .env loader (imported first)
   migrate.ts               applies db/migrations and examples (scripts/migrate.ts, pgkiln migrate); logs each run that applies
   instance.ts              instance settings (meta.setting over environment variables, cached 30 s) and the configuration overview
+  release-check.ts         (sprint 109) "pgkiln X is available": meta.setting 'release_check' over PGKILN_RELEASE_CHECK (off by default);
+                           GitHub's releases/latest (PGKILN_RELEASE_URL in tests), 5 s timeout, 1 MB, cached a day per process,
+                           never under node --test without PGKILN_RELEASE_URL; parseRelease keeps a semver and an https link only
                            or fails a file in public.pgkiln_install_log
   appfiles.ts              application export as one file per component (dir layout, static ids) and back
   blueprint.ts             blueprints (migration 063): checkBlueprint (names, types, references, pages, sample rows), tableOrder,
@@ -30,6 +33,10 @@ src/
                            rows and columns from the response schema, write-back from collection and item paths, notes), catalog
                            files, load/insert/replace, sourceFromService
   workspace-export.ts      (sprint 67) a workspace's components as a file (pgkiln-workspace/1) and importWorkspace (one transaction)
+  team.ts                  (sprint 113) Team Development's data: workspaceDevelopers (members and administrators: assignees, @mentions),
+                           issueHtml (markdownHtml + mentions), recordMentions, logIssue (history), teamSetup, teamCounts, pageIssues,
+                           exportTeam / importTeam (the workspace export's "team" part)
+  team-samples.ts          (sprint 113) the set-up wizard's samples per builder language (English; add a key for another)
   subscriptions.ts         application types and subscriptions (migration 056): offers, subscribe, refresh, publish, in sync
   workingcopy.ts           working copies (migration 055): create, three-way compare per component (base, main, copy),
                            merge into the main application or refresh the copy, both through cli/replace.ts
@@ -52,7 +59,10 @@ src/
   customauth.ts            custom authentication: the app's function or PL/pgSQL body (a pg_temp function) and post-authentication code, as the app's role
   remember.ts              "Keep me signed in": rotating persistent sign-in tokens
   workflow.ts              workflows: step checks, the runner with parallel branches (NOTIFY + polling), invoke_api steps
-                           (the call between two transactions, with a lease), Advisor references, the diagram
+                           (the call between two transactions, with a lease), Advisor references, the diagram;
+                           (sprint 114) send_mail and draft steps, switch cases on task outcomes, the diagram as a standalone SVG
+  task-events.ts           (sprint 114) task events (complete, expire, fail: SQL, mail, start a workflow) and built-in task
+                           notifications from e-mail templates: checks, the actions as the app role, the meta.task_hook outbox runner
   process-jobs.ts          background execution chains: the job queue (SKIP LOCKED, NOTIFY + polling), running a job as the app role
   api.ts                   REST API tokens for PostgREST, API role checks
   accounts.ts              account settings and the password policy
@@ -77,6 +87,13 @@ src/
   datamodel.ts             (sprint 98) Data Modeler diagrams: readModel() (catalog), boxSize(), fkPath() (crow's feet), autoLayout(), diagramSvg()
   changelog.ts             (sprint 106, migration 118) the change log: isSchemaDdl(), ddlTarget() (schema and object), changeName()
                            (add_bonus, create_index_x), recordChanges() (grouped per schema), Flyway / Liquibase / plain SQL writers
+  datasets.ts              (sprint 110, migration 120) Data Reporter datasets: checkDataset() (names, joins to earlier tables, columns
+                           and filters on its tables, whitelisted operators; with a catalog: existing objects), datasetSql() (quoted
+                           identifiers, literal values), readSchemaCatalog() (tables, views, columns, foreign keys), proposeJoin() /
+                           proposeDataset(), storeDataset(), appDatasets() (the runtime's read), pgkiln-dataset/1 files
+  reporting-app.ts         (sprint 110) reporting applications: createReportingApp() (createApp, SELECT-only grants on the datasets'
+                           objects, type reporting, roles viewer/editor/administrator as schemes EDITOR and ADMIN, page 1 a Data
+                           Reporter), reportingApps(), reportingAppCount() (meta.reporting_app_count, for the workspace home)
   tabledef.ts              (sprint 95) a table as a definition: readTable(), checkTable(), tableSql() (CREATE, or ALTER from the catalog's version)
   sqlformat.ts             (sprint 93) formatSql(): the worksheet's Format (clauses per line, keyword case; strings and comments kept)
   sqlplan.ts               (sprint 92) EXPLAIN (FORMAT JSON) as a tree: parsePlan() (self time, slowest step, misestimates), planText()
@@ -128,7 +145,10 @@ src/
                            limits, the call, meta.ai_usage), requests.ts (meta.ai_generate from SQL: runPendingAi() after an sql
                            process, aiRequestTick() in the scheduler, 24-hour purge), chat.ts (conversations with tools, migration
                            061: chat() runs the tool loop on a provider-format history (Claude: streamed, strict tools, tool_choice
-                           auto, content appended unchanged; OpenAI: strict function tools), limits and usage per provider call)
+                           auto, content appended unchanged; OpenAI: strict function tools), limits and usage per provider call;
+                           (121) an agent's effort (Claude output_config.effort, OpenAI reasoning_effort) and output limit).
+                           Providers (121): anthropic, openai, gemini (OpenAI-compatible endpoint, GEMINI_BASE_URL), openai_compatible
+                           (Ollama, vLLM, Azure OpenAI; base URL required, key optional): service.ts serviceKey(), baseUrlFor(), providerLabel()
   debug.ts                 debug messages: DebugLog (levels, timed steps, NOTICEs of meta.debug from appTx), started in
                            loadContext, stored after the response (onResponse hook → meta.debug_save), hourly purge
   icons.ts                 icon helper (sprite in public/icons.svg)
@@ -146,7 +166,7 @@ src/
     styles.ts              base styles (BASE_STYLES: Iris, Lavender, Standard; baseStyleOf → html data-style), Theme Roller style variants: fixed lists (fonts, sizes, corners), parseStyle/appStyles checks, the request's
                            style (user choice, default), themeCss() (only hex values and constants reach the CSS)
     template-options.ts    template options: the fixed CSS class list per region and button, templateClasses() (unknown values ignored)
-    regions.ts             region shell + chart (drill-down links, gauge settings)/cards/dynamic dispatch with row limits, lazy placeholder and cache, buttons (menu buttons, badges)
+    regions.ts             region shell + chart (drill-down links, gauge settings)/cards/dynamic dispatch with row limits, lazy placeholder and cache, buttons (menu buttons, badges; (124) menu entries {action} → data-menu-entry for menu_entry dynamic actions)
     report.ts, report-views.ts (group by, pivot, chart), compute.ts (computed column expressions), grid.ts (aggregates, row actions, Actions menu, single row view, layoutFromForm), grid-layout.ts (column layouts: clean, arrange, per user), master-detail.ts (signed master row selection, details), facets.ts (facetChart: a facet's counts as a chart, sprint 65), items.ts
                            (report.ts: paging with row ranges and max_rows, keyset paging (keysetPlan, seekCondition, signed r<id>_k), pagerNav, streamed CSV/Excel downloads with a cursor;
                            items.ts: lovOptions, searchLov/lovLookup for popup LOVs, served by POST /a/:alias/:page/lov/:item/search in routes.ts)
@@ -183,9 +203,12 @@ src/
     template-components.ts template components: template language (allow-list, directives, escaping), plug-in files, report column templates
     builtin-components.ts  built-in template components (ut_avatar, ut_badge, ut_comments, ut_media_list, ut_metric_card, ut_timeline)
     template-region.ts     template_component region
-    tasks.ts               task list region and task actions (approvals); (094) the vacation rule panel and route
+    tasks.ts               task list region and task actions (approvals); (094) the vacation rule panel and route;
+                           (sprint 114) custom outcome buttons, the Fail event and recovery of a failing completion SQL
     data-reporter.ts       Data Reporter region (migration 057): sources from the region's config, checkDef (offered columns, whitelists),
-                           reportQuery/chartQuery, the list and editor (GET form), save/delete routes (meta.save_data_report)
+                           reportQuery/chartQuery, the list and editor (GET form), save/delete routes (meta.save_data_report);
+                           (sprint 110) dataset sources (resolveSources), edit_authz / admin_authz / publishing, pins (a preference),
+                           publish / pin routes, the stable URL GET /a/:alias/reports/:id
     form-designer.ts       Form Designer region (migration 106): sources from the region's config, checkFormDef (offered columns, displays,
                            actions), forms as cards, a form's rows, a row's form (lost update hash), the designer; row/design/delete routes
     workflows.ts           workflow console region and its actions
@@ -193,8 +216,20 @@ src/
                            schemas from items, answers into items), aiInputs/aiOutputs for its dynamic action (route in routes.ts)
     assistant.ts           AI assistant region (migration 061): config checks, tool schemas and argument checks, context queries
                            and SQL tools as the app role (rolled back unless "writes"), REST tools, meta.ai_conversation per
-                           session, formatAnswer (escaped), send/clear routes
-    ai-filter.ts           natural-language filters on a report ("ai_filter"): columns → structured output → checked → r<id>_f/q/s/d
+                           session, formatAnswer (escaped), send/clear routes; (121) "agent": an AI agent's service, prompt, tools,
+                           steps and authorization; links of navigate tools under the answer, browser actions once (__AIACT<id>)
+    ai-agents.ts           (121) AI agents and AI tools (meta.app.ai_agents / ai_tools): checks (agentProblems, aiToolProblems,
+                           definitionProblems), agentFor(), prepareTools() (authorization schemes, navigate pages the user may
+                           open, strict schemas), runAgentTool() (sql: read-only transaction as the app role with a time limit;
+                           function: named arguments, committed; rest; javascript: queued for the browser; navigate: URL and
+                           checksum built here), logToolCall() (meta.ai_tool_call, debug level 4, 30-day purge)
+    ai-filter.ts           "Ask in your own words" on a report ("ai_filter", sprint 112: AI interactive reports): the box, the chips
+                           form (Edit/Remove/Undo, undo history in the session), ask and chips routes; an AI service's structured
+                           output (planSchema) or the phrase parser, then ir-plan.ts
+    ir-plan.ts             what a question may set: checkPlan (shown columns, whitelists, computeSql), applyPlan (→ the report's
+                           URL parameters), chipsOf/editChip/removeChip (a chip = one URL parameter value, edits checked again)
+    ir-phrases.ts          the rule-based parser without an AI service: phrase tables per language (en, nl, de), clauses →
+                           a RawPlan; values looked up among the report's rows through a Lookup (query parameter)
     pdf.ts                 report PDFs with report layouts (pdfkit); rows from a cursor in batches (tablePdf takes batches)
     search.ts              search region and search configurations (migration 080): words as ILIKE parameters, table/sql/list
                            sources as the app role in savepoints, marked results, configColumns/searchConfigProblems for the Advisor
@@ -217,7 +252,12 @@ src/
     routes.ts              sign-in, app home, settings, activity, developers, create (POST, via newapp.ts)/import (POST)
     wizards.ts             create page wizards: step 2 forms per page type (defaults from meta.wizard_defaults), POST → meta.generate_page
                            (the generators are PL/pgSQL in migration 047: catalog, defaults, form/cards/calendar/chart/map/facets/master-detail)
-    home.ts                App Builder home (tiles, applications report/cards, Recent), Create, Import, Dashboard, Utilities
+    home.ts                App Builder home at /builder/apps and /builder (tiles, applications report/cards, Recent; /builder redirects
+                           to the Workspace home when meta.workspace.builder_home = 'home'), Create, Import, Dashboard, Utilities
+    workspace-home.ts      (sprint 109, migration 119) the Workspace home /builder/home, opened after sign-in: tool cards (Data Reporter
+                           when GET /builder/reporter exists), workspace message edited in place (workspaceAdmin), Summary, Top
+                           applications / users / developers over meta.developer.home_timeframe, System message (src/release-check.ts),
+                           POST timeframe, message, release-check; releaseCheckRegion for Instance settings
     newapp.ts              creating an application (schema, role app_<alias>, Home page, first user): blank app, from a file, from tables
     appfromfile.ts         Create → From a file: upload (src/dataload.ts parsing), proposed table/columns, one transaction:
                            app + table + rows (loadRows) + pages (meta.generate_page: report and form, chart, facets)
@@ -239,6 +279,11 @@ src/
     availability.ts        Application → Availability (migration 083): status, message, users, build status (Run only is
                            enforced by locks.ts blockingLock); availabilityBadge() in the application header
     feedback.ts            Application → Feedback (migration 084): the setting, the list with filters, status and answers
+    team.ts                (sprint 113, migration 122) Builder → Team Development /builder/team: issues (list with filters and saved views,
+                           board by label group or milestone with a Move form per card, issue page with Markdown, comments, canned
+                           responses, @mentions, history), labels and groups, milestones, templates, the set-up wizard; Make an issue
+                           from feedback and developer comments; pageIssuesNote (Page Designer), appIssues (App Home), teamHomeBlock
+                           (Workspace home). Every id from a request is looked up in the current workspace
     region-help.ts         the Attributes (JSON) help per region type, with links to the guide
     mail.ts                Workspace utilities → Mail services (administrators: providers, write-only secret, allowed senders,
                            applications with From and daily limit, test) and Applications → Activity → Mail (retry, cancel)
@@ -305,7 +350,11 @@ src/
     pwa.ts                 Settings → Progressive Web App (icon upload)
     themeroller.ts         Settings → Theme Roller: style variants (add, edit, rename, delete), default style, users may choose
     subscriptions.ts       Shared Components → Subscriptions: subscribe, refresh, unsubscribe, subscribers and publish; the note under a component
-    reporter.ts            page designer: Data Reporter settings (sources: table or view, offered columns, labels, masks; sharing)
+    reporter.ts            page designer: Data Reporter settings (sources: table or view, offered columns, labels, masks; sharing;
+                           (sprint 110) a dataset as a source, who may edit, who may moderate, publishing)
+    datasets.ts            (sprint 110) App Builder → Data Reporter (/builder/reporter): datasets (new: schema, tables; a dataset's
+                           joins, columns, row filter, query and preview), files (download, export all, import), Create reporting
+                           application
     form-designer.ts       page designer: Form Designer settings (designers' scheme; sources: key, actions, offered columns, labels, lists of values)
     workingcopies.ts       Working copies: list and create, compare with differences, merge or refresh with conflict choices, delete
     rest.ts                REST module endpoints list and curl example (Shared Components)
@@ -316,6 +365,8 @@ src/
                            workspace's applications, the module › template › handler tree, handler forms, Try it (inject with a
                            short-lived token), Run only / lock checks
     workflows.ts           workflow versions, diagram and instances (Shared Components)
+    workflow-migrate.ts    (sprint 114) migrating running workflow instances to a newer version (map, preview, apply with
+                           meta.migrate_workflows) and the diagram as an SVG file (PNG in builder.js)
     process-jobs.ts        page designer: the Jobs tab of a background chain process
     template-spec.ts       template component property form (Shared Components)
     websources.ts          web credentials and REST data sources: property specs, secret status, Test, suggested columns,
@@ -338,13 +389,17 @@ src/
     ai-builder.ts          App Builder AI (migration 062): the builder's AI service (meta.builder_ai), SQL Workshop → AI (SQL from a
                            question, shown not run; explain), describe tables (meta.ai_table_note, COMMENT ON, AI drafts),
                            create pages with AI (proposals checked by checkProposals, created with meta.generate_page)
-    assistant.ts           page designer: AI assistant settings and a report's "Ask in your own words" (AI service, placeholder)
+    assistant.ts           page designer: AI assistant settings and a report's "Ask in your own words" (off, built-in phrases or an AI service, placeholder)
     ai.ts                  Workspace utilities → AI services (administrators: services, write-only encrypted keys, access and
                            daily limits per app, Test, usage log) and Activity → AI usage per application
+    ai-agents.ts           (121) Shared Components → AI Agents: the agent and tool forms (checked before saving, renames follow
+                           into agents and regions), toolCallTable() (Activity → AI usage → Tool calls), agentOptions()
     supporting.ts          supporting objects: review page, running the install/upgrade/deinstall scripts as the app's role in one transaction
 public/
   app.css                  theme (light/dark, responsive; --font, --font-size, --radius for style variants; template option classes to-*)
-  app.js                   client runtime: dialogs (dialog_closed actions), popup LOVs, dynamic actions (focus, classes, messages), grids (add/duplicate rows, master-detail refresh, move/resize columns, copy/paste of cell ranges), menus, lazy regions, maps (Leaflet layers, marker clusters, heat layer, layer legend, area/distance filter) (no inline JS)
+  app.js                   client runtime: dialogs (dialog_closed actions), popup LOVs (sprint 115: the next page loads on scroll through an
+                           IntersectionObserver, ‹/More without one), dynamic actions (focus, classes, messages; sprint 115: wait_popup /
+                           remove_wait_popup as a modal <dialog class="wait-popup">, pgkiln.waitPopup(), the menu_entry event), grids (add/duplicate rows, master-detail refresh, move/resize columns, copy/paste of cell ranges), menus, lazy regions, maps (Leaflet layers, marker clusters, heat layer, layer legend, area/distance filter) (no inline JS)
   code-editor.js, .css     builder code editor: enhances <textarea data-code>, highlighting, suggestions (no dependencies);
                            (sprint 108) the current line, and read-only <pre data-code-view="sql|plpgsql|json|html"> highlighted;
                            its colours are the --ce-* tokens in builder.css
@@ -389,6 +444,8 @@ test/
   worksheet.test.ts        (sprint 91) the SQL Worksheet: statement at the cursor, Run Script log, plans, notices, history, navigator, Run as
   worksheet-txn.test.ts    (sprint 107) transaction mode: the tab's transaction, Commit / Rollback, typed COMMIT, aborted, idle timeout, refusals,
                            Explain in it, Change Log at COMMIT, the JSON endpoint, sign-out
+  datasets.test.ts         (sprint 110) datasets: checks and SQL, proposed joins, the builder's pages, files, the workspace export;
+                           a reporting application in two clicks, an editor publishes, a viewer opens the stable URL, pins
   quicksql.test.ts         Quick SQL parser and DDL generator
   xml.test.ts              XML reader: rows, attributes, paths, refused DTDs and entities, limits
   printing.test.ts         report PDFs
@@ -403,6 +460,8 @@ test/
   rest-sources.test.ts     REST data sources, web credentials, SSRF checks, invoke_api (mock service + HR page 23)
   rest-modules.test.ts     (sprint 104) modules, templates, PL/pgSQL and media handlers, OpenAPI, the builder's tree and Try it
   workflow-invoke.test.ts  workflow invoke_api steps: the call between transactions, faults, retry, lease, Advisor, export (mock service)
+  workflow-outcomes.test.ts (sprint 114) custom task outcomes, task events and notifications, fail recovery, send_mail and draft
+                           steps, migrating running instances, the SVG export (HR part 67: SALARY_CHANGE)
   large-tables.test.ts     row ranges, max_rows, row limits, lazy regions, region caching, streamed downloads (HR page 25)
   grid.test.ts             interactive grid: aggregates, layouts per user, saved grid reports, master-detail, row actions (HR page 27)
   custom-auth.test.ts      custom authentication: function body, named function, post-authentication code, builder settings

package/docs/guide/20-ai-agents.md

@@ -7,8 +7,10 @@ it exports the application as files, edits them with its own file tools, shows t
 and imports them again. Laravel developers know the idea from Laravel Boost.
 
 This is separate from the AI features *inside* applications and the builder (AI assistant regions,
-*Generate with AI*): those call a model from pgkiln; here an agent on the developer's machine calls
-pgkiln.
+[AI agents with tools](03-builder.md#ai-agents) in Shared Components, *Generate with AI*): those call a
+model from pgkiln; here an agent on the developer's machine calls pgkiln. An application's AI agents
+and tools are part of its files (`app.json`: `ai_agents`, `ai_tools`), so a coding agent can read and
+change them like any other component.
 
 ## Setting it up
 

package/examples/hr/README.md

@@ -40,6 +40,8 @@ Then open http://127.0.0.1:3100/a/hr and sign in as `king`, `blake`, `jones`, `a
 | `hr_47_plugins.sql` | *Plug-ins* (page 40): the four example plug-ins of `examples/plugins/` (a region, an item, a dynamic action and a process plug-in) |
 | `hr_48_map_tiles.sql` | *Weather stations* (page 41): 20,000 generated stations (`hr.weather_station`) as vector tiles, and the stations above 2,000 m loaded for the visible area |
 | `hr_49_push_notifications.sql` | Push notifications: the app may send them (users turn them on under *My account → Notifications*); a new leave request notifies the manager, a decision notifies the employee, and the notification opens the request (page 7) |
+| `hr_64_ai_agent.sql` | *HR agent* (page 46): the AI agent `HR_AGENT` (Shared Components → AI Agents) with four tools: `top_earners` (SQL, read-only as `hr_app`), `open_employee` (navigate: a link to the employee form with its checksum, only for users who may open page 3), `give_raise` (the PL/pgSQL function `hr.give_raise`, managers only) and `note` (a JavaScript tool: the custom event `hr_agent_note`). Ask *Who in Sales earns most?* Needs an AI service named `HR_ASSISTANT` (see part 41) |
+| `hr_68_component_details.sql` | *Component details* (page 47): a popup LOV over 6,000 rows that loads more as the dialog scrolls, a wait popup around a two-second process (*Recalculate*) and around an Ajax call (*Check in the background*), and an *Actions* menu whose entries run dynamic actions (event `menu_entry`) |
 
 The files run in order, each once (recorded in `public.pgkiln_seed`), so new ones can be added
 later. pgkiln's own tests use this application as their fixture (`npm test` installs it first).

package/examples/hr/hr_63_datasets.sql

@@ -0,0 +1,29 @@
+-- =====================================================================
+-- HR example, part 63: a Data Reporter dataset (docs/guide/04-pages-and-
+-- regions.md, "Datasets and reporting applications")
+--
+-- The dataset "hr" of the Default workspace: employees (hr.emp) joined to
+-- their department (hr.dept, a left join on the foreign key deptno), the
+-- columns business users may see with labels, format masks and
+-- descriptions, and a row filter: active employees only. In the builder,
+-- App Builder → Data Reporter → Create reporting application makes a
+-- reporting application on it in two clicks; datasets are installation
+-- data (a file of their own, and the workspace export), not part of the
+-- HR application's export.
+-- =====================================================================
+
+insert into meta.dataset (workspace_id, name, label, description, schema_name, tables, columns, filters, created_by)
+values (1, 'hr', 'HR', 'Active employees with their department.', 'hr',
+  '[{"alias": "t1", "table": "emp"},
+    {"alias": "t2", "table": "dept", "join": {"to": "t1", "type": "left", "on": [{"column": "deptno", "ref": "deptno"}]}}]',
+  '[{"name": "empno", "table": "t1", "column": "empno", "label": "No."},
+    {"name": "ename", "table": "t1", "column": "ename", "label": "Name"},
+    {"name": "job", "table": "t1", "column": "job", "label": "Job"},
+    {"name": "hiredate", "table": "t1", "column": "hiredate", "label": "Hire date"},
+    {"name": "sal", "table": "t1", "column": "sal", "label": "Salary", "format": "FML999G990D00", "description": "Monthly salary"},
+    {"name": "comm", "table": "t1", "column": "comm", "label": "Commission", "format": "FML999G990D00"},
+    {"name": "dname", "table": "t2", "column": "dname", "label": "Department"},
+    {"name": "loc", "table": "t2", "column": "loc", "label": "Location", "description": "Where the department is"}]',
+  '[{"table": "t1", "column": "active", "op": "eq", "value": "true"}]',
+  'admin')
+on conflict (workspace_id, name) do nothing;

package/examples/hr/hr_64_ai_agent.sql

@@ -0,0 +1,97 @@
+-- =====================================================================
+-- HR example, part 64: an AI agent with tools (sprint 111;
+-- docs/guide/03-builder.md, "AI agents"; APEX 26.1: AI Agents)
+--
+-- Shared Components → AI Agents:
+--   - Tools:
+--       top_earners    (sql)        employees by salary, highest first,
+--                                   optionally of one department: a query
+--                                   run as hr_app (row level security
+--                                   applies) in a read-only transaction
+--       open_employee  (navigate)   a link to the employee form (page 3)
+--                                   with P3_EMPNO: pgkiln offers it only
+--                                   to users who may open page 3
+--                                   (MANAGER) and builds the checksum
+--       give_raise     (function)   hr.give_raise(p_empno, p_pct): changes
+--                                   data, only offered to managers
+--       note           (javascript) shows a message in the browser after
+--                                   the answer (the custom event
+--                                   "hr_agent_note" on page 46)
+--   - Agent HR_AGENT: the AI service HR_ASSISTANT, a system prompt, low
+--     reasoning effort, the four tools, at most 4 steps per question.
+--
+-- Page 46 "HR agent": an AI assistant region that names the agent. Ask
+-- e.g. "Who in Sales earns most?": the agent calls top_earners and offers
+-- "Open BLAKE's record", a link to page 3 with a valid checksum.
+--
+-- Like parts 41 and 42 the example creates no AI service: an administrator
+-- adds one named HR_ASSISTANT under App Builder → Workspace utilities → AI
+-- services (Claude, OpenAI, Gemini or an OpenAI-compatible endpoint) and
+-- allows the HR application to use it.
+-- =====================================================================
+
+update meta.app set
+  ai_tools = $j$[
+    {"name": "top_earners", "type": "sql",
+     "description": "Active employees with their job, department and salary, highest salary first; optionally only one department (case-insensitive name, e.g. SALES).",
+     "sql": "select empno, ename, job, dname, sal from hr.staff_v where active and (:DNAME is null or dname ilike :DNAME) order by sal desc, ename",
+     "parameters": {"DNAME": {"type": "string", "optional": true, "description": "A department name, e.g. SALES."}},
+     "max_rows": 20, "timeout_s": 10},
+    {"name": "open_employee", "type": "navigate",
+     "description": "Offer the user a link to an employee's record (the employee form). Use the employee number (empno) as P3_EMPNO and a label such as \"Open BLAKE's record\".",
+     "pages": [3]},
+    {"name": "give_raise", "type": "function",
+     "description": "Raise an employee's salary by a percentage. Only when the user clearly asks for it; repeat the employee and the percentage first.",
+     "function": "hr.give_raise",
+     "parameters": {"P_EMPNO": {"type": "integer", "description": "The employee number (empno)."},
+                    "P_PCT": {"type": "number", "description": "The raise in percent, e.g. 5."}},
+     "authz": "MANAGER"},
+    {"name": "note", "type": "javascript", "action": "hr_agent_note",
+     "description": "Show the user a short confirmation message in the page, e.g. after a raise.",
+     "parameters": {"TEXT": {"type": "string", "description": "The message."}}}
+  ]$j$::jsonb,
+  ai_agents = $j$[
+    {"name": "HR_AGENT", "description": "Answers questions about salaries and opens employee records",
+     "service": "HR_ASSISTANT",
+     "system": "You are the HR agent of a small company, talking with &APP_USER.. Answer questions about employees, departments and salaries with the top_earners tool. When you name one employee, offer a link to their record with open_employee (the empno as P3_EMPNO). Be brief.",
+     "effort": "low", "tools": ["top_earners", "open_employee", "give_raise", "note"], "max_steps": 4, "max_tokens": 2000}
+  ]$j$::jsonb
+ where alias = 'hr';
+
+insert into meta.page (app_id, page_no, name, title, parent_page)
+select id, 46, 'HR agent', 'HR agent', 1 from meta.app where alias = 'hr';
+
+insert into meta.region (page_id, seq, title, type, columns, template, source, condition, config)
+select p.id, r.seq, r.title, r.type, r.cols, 'standard', r.source, r.cond, r.config::jsonb
+  from meta.page p join meta.app a on a.id = p.app_id, (values
+  (10, 'No AI service yet', 'static', 12,
+   '<p class="alert alert-info">No AI service is configured for this application yet. An administrator adds an AI service named <b>HR_ASSISTANT</b> under <i>App Builder → Workspace utilities → AI services</i> and allows the HR application to use it.</p>',
+   'not meta.ai_available(''HR_ASSISTANT'')', '{}'),
+  (20, 'Ask the HR agent', 'ai_assistant', 8, null, 'meta.ai_available(''HR_ASSISTANT'')',
+   $j${"agent": "HR_AGENT",
+       "welcome": "Hello! Ask me who earns what, e.g. who in Sales earns most. I can open an employee's record for you.",
+       "placeholder": "e.g. Who in Sales earns most?",
+       "max_turns": 20,
+       "error_message": "The HR agent could not answer just now. Please try again later."}$j$)
+  ) as r (seq, title, type, cols, source, cond, config)
+ where a.alias = 'hr' and p.page_no = 46;
+
+-- the javascript tool "note": a custom event the agent raises after its answer
+insert into meta.dynamic_action (page_id, seq, name, event, trigger_element, action, message)
+select p.id, 10, 'Agent note', 'custom', 'hr_agent_note', 'show_success', 'The HR agent did what you asked.'
+  from meta.page p join meta.app a on a.id = p.app_id where a.alias = 'hr' and p.page_no = 46;
+
+insert into meta.nav_entry (app_id, seq, label, icon, target_page)
+select id, 30, 'HR agent', 'users', 46 from meta.app where alias = 'hr';
+
+insert into meta.translation (app_id, language, source, target)
+select a.id, 'nl', t.source, t.target
+  from meta.app a, (values
+  ('HR agent', 'HR-agent'),
+  ('Ask the HR agent', 'Vraag het de HR-agent'),
+  ('Hello! Ask me who earns what, e.g. who in Sales earns most. I can open an employee''s record for you.',
+   'Hallo! Vraag me wie wat verdient, bijv. wie in Sales het meest verdient. Ik kan ook de gegevens van een medewerker voor je openen.'),
+  ('e.g. Who in Sales earns most?', 'bijv. Wie verdient het meest in Sales?')
+  ) as t (source, target)
+ where a.alias = 'hr'
+on conflict do nothing;

package/examples/hr/hr_65_ask_reports.sql

@@ -0,0 +1,21 @@
+-- =====================================================================
+-- HR example, part 65: "Ask in your own words" without an AI service
+-- (docs/guide/04-pages-and-regions.md, "Ask in your own words")
+--
+-- Page 2 "Employees": the interactive report gets a question box with the
+-- built-in phrases ("ai_filter": {} names no AI service). Try
+--   sum of salary by department where job is clerk
+--   salary over 2500, sort by hire date, newest first
+--   only clerks hired after 1981
+--   bonus is 10% of salary
+--   highlight salary over 4000 in red
+-- Each answer becomes the report's own settings (filters, sort, group by,
+-- computed columns, …), shown as chips with Edit and Remove under the box;
+-- Undo goes back a step. Page 38's staff list uses the HR_ASSISTANT AI
+-- service when an administrator has added it, else the same phrases.
+-- =====================================================================
+
+update meta.region r
+   set config = r.config || '{"ai_filter": {"placeholder": "e.g. sum of salary by department where job is clerk"}}'
+  from meta.page p, meta.app a
+ where r.page_id = p.id and p.app_id = a.id and a.alias = 'hr' and p.page_no = 2 and r.type = 'report';

package/examples/hr/hr_66_team_development.sql

@@ -0,0 +1,58 @@
+-- =====================================================================
+-- HR example, part 66: Team Development (docs/guide/03-builder.md,
+-- "Team Development")
+--
+-- What Builder → Team Development → Set up installs in the Default
+-- workspace (the label groups Type and Priority, milestones 1.0 and 1.1,
+-- a bug report template and a canned response), and one issue about the
+-- HR application: "Salary rounding on page 12", a Bug of milestone 1.1,
+-- assigned to admin. The Page Designer of page 12 shows it, and the
+-- Workspace home counts it until it is closed. Issues are workspace data
+-- (the workspace export), not part of the HR application's export.
+-- =====================================================================
+
+insert into meta.team_label_group (workspace_id, name, description, seq) values
+  (1, 'Type', 'What kind of work the issue is.', 10),
+  (1, 'Priority', 'How soon it should be done.', 20)
+on conflict (workspace_id, lower(name)) do nothing;
+
+insert into meta.team_label (workspace_id, group_id, name, color, description, seq)
+select 1, g.id, l.name, l.color, l.description, l.seq
+  from (values ('Type', 'Bug', 'red', 'Something does not work as it should.', 10),
+               ('Type', 'Feature', 'blue', 'New functionality.', 20),
+               ('Type', 'Task', 'teal', 'Work to do that is neither a bug nor a feature.', 30),
+               ('Priority', 'High', 'orange', 'Do this first.', 10),
+               ('Priority', 'Medium', 'yellow', 'Do this soon.', 20),
+               ('Priority', 'Low', 'gray', 'Do this when there is time.', 30)) as l(grp, name, color, description, seq)
+  join meta.team_label_group g on g.workspace_id = 1 and g.name = l.grp
+on conflict (workspace_id, lower(name)) do nothing;
+
+insert into meta.team_milestone (workspace_id, name, description, due_date) values
+  (1, '1.0', 'The first release.', current_date + 30),
+  (1, '1.1', 'The first update after the release.', current_date + 90)
+on conflict (workspace_id, lower(name)) do nothing;
+
+insert into meta.team_template (workspace_id, kind, name, title, body, labels, seq) values
+  (1, 'issue', 'Bug report', 'Bug: ', E'## What happens\n\n\n## What should happen\n\n\n## Steps to reproduce\n\n1. \n2. \n', '{Bug}', 10),
+  (1, 'response', 'Thanks, we will look at it', null, 'Thank you for reporting this. We will look at it and keep this issue up to date.', '{}', 10)
+on conflict (workspace_id, kind, lower(name)) do nothing;
+
+with issue as (
+  insert into meta.team_issue (workspace_id, title, body, milestone_id, app_id, page_no, created_by)
+  select 1, 'Salary rounding on page 12',
+         E'The leave calendar shows daily salary costs rounded to whole euros; finance expects cents.\n\n'
+         || E'- Open **page 12** (Leave calendar)\n- Compare a day with the salary in `hr.emp`\n\n@admin can you have a look?',
+         (select id from meta.team_milestone where workspace_id = 1 and name = '1.1'),
+         a.id, 12, 'admin'
+    from meta.app a
+   where a.alias = 'hr'
+     and not exists (select 1 from meta.team_issue i where i.workspace_id = 1 and i.title = 'Salary rounding on page 12')
+  returning id
+), labelled as (
+  insert into meta.team_issue_label (issue_id, label_id)
+  select issue.id, l.id from issue join meta.team_label l on l.workspace_id = 1 and l.name in ('Bug', 'Medium')
+), assigned as (
+  insert into meta.team_issue_assignee (issue_id, username)
+  select issue.id, 'admin' from issue where exists (select 1 from meta.developer where username = 'admin')
+)
+insert into meta.team_issue_event (issue_id, username, action) select id, 'admin', 'created' from issue;

package/examples/hr/hr_67_workflow_outcomes.sql

@@ -0,0 +1,113 @@
+-- =====================================================================
+-- HR example, part 67: custom task outcomes, task events and
+-- notifications, a Send E-Mail step, drafts and versions of a workflow
+-- (migration 123; docs/guide/06-processing.md, "Approvals" and "Workflows")
+--
+-- SALARY_DECISION is a task with three outcomes instead of Approve / Reject:
+-- Yes, No and Undecided. Its owners (role admin) get an e-mail when a task
+-- is created (notification SALARY_TASK); when one is completed an event
+-- records the decision as a notification for the initiator.
+--
+-- SALARY_CHANGE asks for that decision and branches on its outcome:
+--   1. APPROVE  the task (an administrator decides)
+--   2. DECIDE   YES: apply the new salary; UNDECIDED: ask again; otherwise the end
+--   3. APPLY    the new salary (SQL)
+--   4. TELL     an e-mail to the employee (version 2: a send_mail step)
+-- Version 1 had no TELL step and is inactive; version 2 is active; version 3
+-- is in development with a draft step (BUDGET_CHECK) that is still a
+-- placeholder: it is drawn dashed, and can't be activated until it is
+-- replaced. Instances of version 1 can be migrated to version 2 under
+-- Shared Components → Workflows → SALARY_CHANGE → Migrate running instances.
+--
+-- Start one from SQL (e.g. the SQL Workshop, signed in to the application):
+--   select meta.start_workflow('SALARY_CHANGE', '7499', '{"ENAME": "Allen", "NEW_SAL": 1760}')
+-- and decide on it under My tasks (page 14) as king.
+-- =====================================================================
+
+insert into meta.email_template (app_id, name, subject, html_body, text_body)
+select id, 'SALARY_TASK', 'To decide: #SUBJECT#',
+$h$<p>A salary change waits for your decision: <b>#SUBJECT#</b>.</p>
+<p>Requested by #INITIATOR#. Decide under <i>My tasks</i> in HR Demo.</p>$h$,
+$t$A salary change waits for your decision: #SUBJECT#.
+
+Requested by #INITIATOR#. Decide under "My tasks" in HR Demo.$t$
+  from meta.app where alias = 'hr'
+union all
+select id, 'SALARY_CHANGED', 'Your salary changes to #NEW_SAL#',
+$h$<p>Dear #ENAME#,</p><p>Your new salary of <b>#NEW_SAL#</b> was approved by #TASK_APPROVER#.</p><p>Kind regards,<br>HR</p>$h$,
+$t$Dear #ENAME#,
+
+Your new salary of #NEW_SAL# was approved by #TASK_APPROVER#.
+
+Kind regards,
+HR$t$
+  from meta.app where alias = 'hr';
+
+insert into meta.task_definition (app_id, name, type, subject, owner_roles, admin_role, priority, due_in, outcomes, events, notifications)
+select id, 'SALARY_DECISION', 'approval', 'Salary of &ENAME. to &NEW_SAL.', '{admin}'::text[], 'admin', 2, '5 days',
+       $o$[{"name": "YES", "label": "Yes", "colour": "success"},
+           {"name": "NO", "label": "No", "colour": "danger"},
+           {"name": "UNDECIDED", "label": "Undecided", "colour": "warning"}]$o$::jsonb,
+       $e$[{"on": "complete", "type": "sql", "code": "select hr.salary_decided(:DETAIL_PK::int, :OUTCOME, :INITIATOR)"}]$e$::jsonb,
+       '{"create": "SALARY_TASK"}'::jsonb
+  from meta.app where alias = 'hr';
+
+-- Notifications are for other users, which RLS forbids the app: security definer, like the onboarding ones.
+create function hr.salary_decided(p_empno int, p_outcome text, p_initiator text) returns void
+language plpgsql security definer set search_path = hr, pg_catalog as $$
+begin
+  insert into hr.notification (username, message)
+  select p_initiator, format('Salary change of %s: %s.', initcap(e.ename), lower(p_outcome))
+    from hr.emp e where e.empno = p_empno;
+end
+$$;
+create function hr.salary_change_apply(p_empno int, p_sal numeric) returns timestamptz
+language plpgsql security definer set search_path = hr, pg_catalog as $$
+begin
+  if p_sal is null or p_sal <= 0 then
+    raise exception 'A salary is more than 0.';
+  end if;
+  update hr.emp set sal = p_sal where empno = p_empno;
+  return now();
+end
+$$;
+-- the e-mail address of an employee's account (the accounts are pgkiln's, not the application's)
+create function hr.employee_email(p_empno int) returns text
+language sql stable security definer set search_path = hr, pg_catalog as $$
+  select a.email from hr.emp e join meta.account a on lower(a.username) = lower(e.username) where e.empno = p_empno and a.active
+$$;
+revoke all on function hr.salary_decided(int, text, text), hr.salary_change_apply(int, numeric), hr.employee_email(int) from public;
+grant execute on function hr.salary_decided(int, text, text), hr.salary_change_apply(int, numeric), hr.employee_email(int) to hr_app;
+
+-- version 1, then version 2 (with the e-mail) becomes active, then version 3 in development (a draft step)
+insert into meta.workflow_definition (app_id, name, title, description, admin_role, steps)
+select id, 'SALARY_CHANGE', 'Salary of &ENAME. to &NEW_SAL.', 'A salary change, decided by an administrator (Yes, No or Undecided).', 'admin',
+$s$[
+  {"name": "APPROVE", "type": "task", "task": "SALARY_DECISION"},
+  {"name": "DECIDE", "type": "switch", "cases": [{"outcome": "YES", "next": "APPLY"}, {"outcome": "UNDECIDED", "next": "APPROVE"}], "otherwise": "END"},
+  {"name": "APPLY", "type": "sql", "code": "select hr.salary_change_apply(:DETAIL_PK::int, :NEW_SAL::numeric) as applied_at", "next": "END"},
+  {"name": "END", "type": "end"}
+]$s$::jsonb
+  from meta.app where alias = 'hr';
+
+select meta.new_workflow_version(d.id) from meta.workflow_definition d join meta.app a on a.id = d.app_id where a.alias = 'hr' and d.name = 'SALARY_CHANGE';
+update meta.workflow_definition d set dev_steps = $s$[
+  {"name": "APPROVE", "type": "task", "task": "SALARY_DECISION"},
+  {"name": "DECIDE", "type": "switch", "cases": [{"outcome": "YES", "next": "APPLY"}, {"outcome": "UNDECIDED", "next": "APPROVE"}], "otherwise": "END"},
+  {"name": "APPLY", "type": "sql", "code": "select hr.salary_change_apply(:DETAIL_PK::int, :NEW_SAL::numeric) as applied_at"},
+  {"name": "TELL", "type": "send_mail", "to": "select hr.employee_email(:DETAIL_PK::int)", "template": "SALARY_CHANGED", "next": "END"},
+  {"name": "END", "type": "end"}
+]$s$::jsonb
+  from meta.app a where a.id = d.app_id and a.alias = 'hr' and d.name = 'SALARY_CHANGE';
+select meta.activate_workflow_version(d.id) from meta.workflow_definition d join meta.app a on a.id = d.app_id where a.alias = 'hr' and d.name = 'SALARY_CHANGE';
+
+select meta.new_workflow_version(d.id) from meta.workflow_definition d join meta.app a on a.id = d.app_id where a.alias = 'hr' and d.name = 'SALARY_CHANGE';
+update meta.workflow_definition d set dev_steps = $s$[
+  {"name": "BUDGET_CHECK", "type": "draft", "note": "check the department's budget", "next": "APPROVE"},
+  {"name": "APPROVE", "type": "task", "task": "SALARY_DECISION"},
+  {"name": "DECIDE", "type": "switch", "cases": [{"outcome": "YES", "next": "APPLY"}, {"outcome": "UNDECIDED", "next": "APPROVE"}], "otherwise": "END"},
+  {"name": "APPLY", "type": "sql", "code": "select hr.salary_change_apply(:DETAIL_PK::int, :NEW_SAL::numeric) as applied_at"},
+  {"name": "TELL", "type": "send_mail", "to": "select hr.employee_email(:DETAIL_PK::int)", "template": "SALARY_CHANGED", "next": "END"},
+  {"name": "END", "type": "end"}
+]$s$::jsonb
+  from meta.app a where a.id = d.app_id and a.alias = 'hr' and d.name = 'SALARY_CHANGE';