@genesislcap/blank-app-seed 5.27.2-prerelease.3 → 5.28.0

package/.genx/tests/contracts/ai/ui-config-ai.schema.json

@@ -0,0 +1,203 @@
+{
+  "$schema": "https://json-schema.org/draft/2019-09/schema",
+  "$id": "https://genesis.global/schemas/create/ui-config-ai.schema.json",
+  "title": "ui.config.ai",
+  "version": "1.6.0",
+  "description": "The AI chat block a generated app reads from ui.config (GENC-1601 contract C-8). Produced by the archive service's ai-resolver from the project payload, and copied VERBATIM into the seed — both sides pin this file's digest, so a change here is a deliberate version bump, not an edit. It carries WHAT the chat may do and nothing about WHERE it talks: no url, endpoint, key or budget field exists, and additionalProperties is false everywhere so one cannot be added by accident. That is load-bearing — this block is written into the generated app's genesis-create.json and ships in the exported project, so a Create endpoint or key here would leave the box.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["enabled", "vendor", "tier", "systemPrompt", "resources"],
+  "properties": {
+    "enabled": {
+      "type": "boolean",
+      "description": "Emitted only for a project that selected AI chat; the block is absent entirely otherwise, so a project without AI stays byte-identical (C57)."
+    },
+    "vendor": {
+      "enum": ["gemini", "anthropic"],
+      "description": "Default 'gemini' (R-7). The generated app resolves a provider for it; the endpoint is supplied by the build environment, never from here."
+    },
+    "tier": {
+      "enum": ["low", "high", "reasoning"],
+      "description": "Default 'high' (R-7). Maps to a model through the foundation-ui tier table (C-3), so no model id appears in a generated project."
+    },
+    "systemPrompt": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The assistant's standing instruction. Derived deterministically from the project, so regenerating an unchanged project produces an unchanged file."
+    },
+    "resources": {
+      "type": "array",
+      "uniqueItems": true,
+      "description": "What the chat may read and call, by the name the platform actually registers. A name that matches nothing is dropped silently by the runtime (C34), so these are derived from the project rather than typed by hand. One entry per name: the chat tolerates a duplicate, but MCP's enableMcp refuses the whole script over one, so the resolver dedupes and both consumers can trust it.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "kind", "context"],
+        "properties": {
+          "name": {
+            "type": "string",
+            "pattern": "^[A-Z][A-Z0-9_]*$",
+            "maxLength": 64,
+            "description": "REQ_<NAME> for a request-server resource, EVENT_<NAME> for an event handler, and a dataserver query's own name, which is neither (C-15A.5 K-2). Never the bare MCP resource name (C34). At most 64 characters: the assistant's tool name is this name lowercased, and vendors reject longer tool names."
+          },
+          "kind": {
+            "enum": ["request", "event", "query"],
+            "description": "'request' is a read through the request server; 'event' is a write through an event handler; 'query' is a read of a dataserver query's live rows (C-15). A seed passes 'query' on only when its UI reads it (C-15A.5)."
+          },
+          "op": {
+            "enum": ["insert", "modify", "delete", "custom"],
+            "description": "Events only, in the platform's WIRE vocabulary. The project meta says create/update/delete; the resolver maps create→insert and update→modify so nothing downstream knows two names for one thing."
+          },
+          "context": {
+            "type": "string",
+            "minLength": 1,
+            "description": "One line telling the model what this resource is for."
+          },
+          "maxRows": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 1000,
+            "description": "Requests and queries only; the resolver emits 50. A row cap in the host bridge applies regardless — this is guidance, not enforcement."
+          },
+          "shape": {
+            "enum": ["row"],
+            "description": "Custom events only (C-18.3). 'row': the handler's code was proven to change one existing row of entity, looked up by its primary key, and optionally insert rows elsewhere. A new meaning gets a new value, never a looser 'row'."
+          },
+          "entity": {
+            "type": "string",
+            "pattern": "^[A-Z0-9_]+$",
+            "description": "The table a resource acts on. Allowed on any resource with that one meaning (C-8); required with shape, where the bridge reads the row through REQ_<entity>."
+          },
+          "key": {
+            "type": "array",
+            "minItems": 1,
+            "uniqueItems": true,
+            "items": { "type": "string", "pattern": "^[A-Z0-9_]+$", "not": { "enum": ["RECORD_ID", "TIMESTAMP"] } },
+            "description": "The table's primary-key fields, in primary-key order. On a row action, the row the handler loads is the row the review shows; on a modify or a delete, the row the write names. RECORD_ID and TIMESTAMP are the platform's own and never a key."
+          },
+          "inputs": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["field", "required"],
+              "properties": {
+                "field": { "type": "string", "pattern": "^[A-Z0-9_]+$" },
+                "required": { "const": true }
+              }
+            },
+            "description": "The fields the handler's code reads from the request beyond the key. May be empty. Every input is required in v1, and the constant is written so the bridge checks it rather than assumes it."
+          },
+          "effects": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["op", "table"],
+              "properties": {
+                "op": { "enum": ["modify", "insert"] },
+                "table": { "type": "string", "pattern": "^[A-Z0-9_]+$" }
+              }
+            },
+            "contains": { "required": ["op"], "properties": { "op": { "const": "modify" } } },
+            "minContains": 1,
+            "maxContains": 1,
+            "description": "One per write call in the handler's code, in code order: exactly one modify, of entity, and any inserts."
+          },
+          "customCode": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["alsoWrites", "listComplete"],
+            "properties": {
+              "alsoWrites": {
+                "type": "array",
+                "uniqueItems": true,
+                "items": { "type": "string", "pattern": "^[A-Z0-9_]+$" },
+                "description": "Tables other than its own that the op's custom code provably writes to, in the order it first writes each. A floor, never the whole story on its own."
+              },
+              "listComplete": {
+                "type": "boolean",
+                "description": "True only when every write, call and way out of the code was accounted for, so alsoWrites names every other table it writes."
+              }
+            },
+            "description": "A CRUD event whose handler runs custom code (C-18.D): the review tells the user that the code can do more than save the values shown."
+          },
+          "references": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["resource", "fields"],
+              "properties": {
+                "resource": { "type": "string", "pattern": "^REQ_[A-Z0-9_]+$" },
+                "fields": {
+                  "type": "array",
+                  "minItems": 1,
+                  "items": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["field", "targetField"],
+                    "properties": {
+                      "field": { "type": "string", "pattern": "^[A-Z0-9_]+$" },
+                      "targetField": { "type": "string", "pattern": "^[A-Z0-9_]+$" }
+                    }
+                  }
+                }
+              }
+            },
+            "description": "Declared references of this write, for the bridge's existence check. Absent on a config older than this version, when the app's seed does not declare references, when an upstream pre-resolved block omits it, or when Create had no fields list for the table; [] means the table declares none. Only an insert or modify event carries it. Two rules the schema cannot say: a field appears at most once across all groups, and a group's targetField values are distinct; the resolver guarantees both by construction and its resourceProblem checks them on the pre-resolved path."
+          }
+        },
+        "$comment": "The kind decides the rest, and the name's prefix must fit it, as in the foundation-ui assistant's validateGenesisAiConfig, which blocks the WHOLE assistant on any mismatch. These rules mirror it, with two things a schema cannot say: two resources sharing a name but differing in another field pass uniqueItems (it only rejects identical items) yet block the assistant, which is why the resolver dedupes by name; and enabled false is valid here because it is a deliberate off, not a block the assistant will run. A row action (shape) has three more the schema cannot say, enforced by the resolver and mirrored by the bridge's rowActionProblem: the modify effect's table is entity; no key field is also an input; and REQ_<entity> is a request resource in the same block.",
+        "allOf": [
+          {
+            "description": "A request is a REQ_ name, and no op.",
+            "if": { "properties": { "kind": { "const": "request" } } },
+            "then": { "properties": { "name": { "pattern": "^REQ_[A-Z0-9_]+$" } }, "not": { "required": ["op"] } }
+          },
+          {
+            "description": "An event is an EVENT_ name, an op, and no maxRows.",
+            "if": { "properties": { "kind": { "const": "event" } } },
+            "then": { "properties": { "name": { "pattern": "^EVENT_[A-Z0-9_]+$" } }, "required": ["op"], "not": { "required": ["maxRows"] } }
+          },
+          {
+            "description": "A query is a name that is neither a request's nor an event's, and no op (C-15A.5 K-2, K-3).",
+            "if": { "properties": { "kind": { "const": "query" } } },
+            "then": { "properties": { "name": { "not": { "pattern": "^(REQ|EVENT)_" } } }, "not": { "required": ["op"] } }
+          },
+          {
+            "description": "A row action's companions ride a custom op with shape only, and with shape all four are required. key may also ride a modify or a delete (below).",
+            "if": { "required": ["op", "shape"], "properties": { "op": { "const": "custom" } } },
+            "then": { "required": ["entity", "key", "inputs", "effects"] },
+            "else": {
+              "not": {
+                "anyOf": [{ "required": ["shape"] }, { "required": ["inputs"] }, { "required": ["effects"] }]
+              }
+            }
+          },
+          {
+            "description": "key rides a custom op with shape (above) or a modify or delete event (C-19.1). op is required in each branch: an absent op would satisfy it vacuously.",
+            "if": { "required": ["key"] },
+            "then": {
+              "anyOf": [
+                { "required": ["op", "shape"], "properties": { "op": { "const": "custom" } } },
+                { "required": ["op"], "properties": { "op": { "enum": ["modify", "delete"] } } }
+              ]
+            }
+          },
+          {
+            "description": "customCode rides an insert, modify or delete event only. op is required here: an absent op would satisfy an if on op vacuously.",
+            "if": { "required": ["customCode"] },
+            "then": { "required": ["op"], "properties": { "op": { "enum": ["insert", "modify", "delete"] } } }
+          },
+          {
+            "description": "references ride an insert or modify event only (C-17.3). op is required in the if: an absent op would satisfy it vacuously.",
+            "if": { "required": ["op"], "properties": { "op": { "enum": ["insert", "modify"] } } },
+            "else": { "not": { "required": ["references"] } }
+          }
+        ]
+      }
+    }
+  }
+}

package/.genx/tests/fixtures/ai-config-parse-breakers.json

@@ -0,0 +1,16 @@
+{
+  "ai": {
+    "enabled": true,
+    "vendor": "gemini",
+    "tier": "high",
+    "systemPrompt": "Text Handlebars cannot even parse: {{#if}} opens a block with no argument, {{{ never closes, and {{#each items}} is never closed.",
+    "resources": [
+      {
+        "name": "REQ_TRADE",
+        "kind": "request",
+        "context": "Trades, {{#unless}}.",
+        "maxRows": 50
+      }
+    ]
+  }
+}

package/.genx/tests/fixtures/ai-config.json

@@ -0,0 +1,41 @@
+{
+  "ai": {
+    "enabled": true,
+    "vendor": "gemini",
+    "tier": "high",
+    "systemPrompt": "You are the assistant for {{appName}}{{! a comment }}. Keep \\{{this}}, {{#if AI.enabled}}shown{{/if}}, {{#if x}}hidden{{/if}} and {{{that}}} literal; \"quotes\", </script>, ünïcödé and the text \\u007b must survive.",
+    "resources": [
+      {
+        "name": "REQ_TRADE",
+        "kind": "request",
+        "context": "Trades booked in {{appName}}.",
+        "maxRows": 50
+      },
+      {
+        "name": "EVENT_TRADE_INSERT",
+        "kind": "event",
+        "op": "insert",
+        "context": "Book a new trade.",
+        "customCode": { "alsoWrites": ["POSITION"], "listComplete": false },
+        "references": [
+          { "resource": "REQ_COUNTERPARTY", "fields": [{ "field": "COUNTERPARTY_ID", "targetField": "COUNTERPARTY_ID" }] }
+        ]
+      },
+      {
+        "name": "EVENT_TRADE_MODIFY",
+        "kind": "event",
+        "op": "modify",
+        "context": "Change a trade.",
+        "references": [
+          { "resource": "REQ_COUNTERPARTY", "fields": [{ "field": "COUNTERPARTY_ID", "targetField": "COUNTERPARTY_ID" }] }
+        ]
+      },
+      {
+        "name": "REQ_COUNTERPARTY",
+        "kind": "request",
+        "context": "Counterparties a trade can name.",
+        "maxRows": 50
+      }
+    ]
+  }
+}

package/.genx/versions.json

@@ -1,5 +1,5 @@
 {
-  "UI": "15.39.0",
-  "GSF": "10.0.0-beta4",
-  "Auth": "10.0.0-beta4"
+  "UI": "15.50.0",
+  "GSF": "8.15.14",
+  "Auth": "8.15.3"
 }

package/.github/workflows/build.yml

@@ -12,15 +12,17 @@ concurrency:
 jobs:
   # The `build` job below covers React end to end (gradle build, lint, unit + e2e) for
   # the defaults app. This job keeps every framework's generator honest: for each one it
-  # generates the defaults app, the full-routes fixture app and an FDC3-channels app,
-  # and runs the ox lint gates over all three.
+  # generates the defaults app, the full-routes fixture app and an FDC3-channels app, plus
+  # for React an app with the AI chat on, and runs the ox lint gates over each.
   #
   # BUILD=1 adds `tsc --noEmit` and the production build per app, which is what makes a
   # broken generated tile fail here. Lint alone does not type-check, and the app the
   # `build` job below compiles is the defaults one, which generates no tiles at all, so
   # before this nothing compiled a generated tile: a grid tile passed a prop the React
   # wrapper's types did not declare and CI stayed green while `npm run build` failed for
-  # anyone scaffolding with routes.
+  # anyone scaffolding with routes. For the AI app it also checks that the assistant and
+  # its bubble are built into a chunk of their own, and into no other, and that the seed's
+  # AI declaration holds the baseline and names nothing the installed assistant does not read.
   generated-apps:
     strategy:
       fail-fast: false
@@ -37,9 +39,15 @@ jobs:
         with:
           node-version: 22
 
-      - name: Generate and lint ${{ matrix.framework }} apps (default + full + fdc3)
+      - name: Generate and lint ${{ matrix.framework }} apps (default + full + fdc3, and ai for React)
         run: ./.genx/scripts/generate-test-apps.sh ${{ matrix.framework }}
 
+      # Generates its own React and web-components apps, so one leg is enough. This job has no Java
+      # or artifactory credentials, so it runs the emission checks only; the build job adds GRADLE=1.
+      - name: Check what the AI chat path emits
+        if: matrix.framework == 'react'
+        run: ./.genx/scripts/check-ai-emission.sh
+
   build:
     env:
       genesisArtifactoryUser: ${{ secrets.JFROG_LIBS_RELEASE_CLIENT_RO_USER }}
@@ -79,6 +87,14 @@ jobs:
         working-directory: /tmp/testapp
         run: ./gradlew ${GRADLE_PARAMS} build --info
 
+      # The AI chat proxy is a script, and scripts compile only when the router starts, so no build
+      # compiles it. This one builds an AI app, runs the security scan on it and compiles both
+      # vendors' proxies against this Genesis version. It picks up GRADLE_PARAMS from the job.
+      - name: Build, scan and compile the AI chat proxy
+        env:
+          GRADLE: 1
+        run: ./.genx/scripts/check-ai-emission.sh
+
       - name: Lint UI
         working-directory: /tmp/testapp/client
         run: npm run lint

package/CHANGELOG.md

@@ -1,48 +1,60 @@
 # Changelog
 
-## [5.27.2-prerelease.3](https://github.com/genesiscommunitysuccess/blank-app-seed/compare/v5.27.2-prerelease.2...v5.27.2-prerelease.3) (2026-09-29)
-
-
-### Bug Fixes
-
-* updating server version information for Auth [PSD-0](https://github.com/genesiscommunitysuccess/blank-app-seed/issues/0) 3130813
-
-## [5.27.2-prerelease.2](https://github.com/genesiscommunitysuccess/blank-app-seed/compare/v5.27.2-prerelease.1...v5.27.2-prerelease.2) (2026-09-29)
-
-
-### Bug Fixes
-
-* updating server version information for GSF [PSD-0](https://github.com/genesiscommunitysuccess/blank-app-seed/issues/0) 7dfb94d
-
-## [5.27.2-prerelease.1](https://github.com/genesiscommunitysuccess/blank-app-seed/compare/v5.27.1...v5.27.2-prerelease.1) (2026-09-29)
-
-
-### Bug Fixes
-
-* address release workflow review comments 67ce8c3
-* address second round of release workflow review comments 4a1c5f5
-* backport main to prerelease [PSD-0](https://github.com/genesiscommunitysuccess/blank-app-seed/issues/0) (#599) 841793f
-* backport main to prerelease [PSD-0](https://github.com/genesiscommunitysuccess/blank-app-seed/issues/0) (#616) 545eb21
-* Bump BDD framework (bddVersion) from 3.5.30 to 3.5.73 GENC-0 (#609) 4b8bb58
-* **client:** resolve the client buildscript from Artifactory (GSF-8370) 489b951
-* **client:** resolve the client buildscript from Artifactory (GSF-8370) (#633) ede81ee
-* default dist-tag to latest when semantic-release channel is null ce5a216
-* merge main into prerelease GENC-1362 (#589) c7eed71
-* resolve from Artifactory before Maven Central in every module (GSF-8370) 2a263c2
-* **server:** query the Plugin Portal before Maven Central (GSF-8370) 725b377
-* **server:** resolve from Artifactory before Maven Central (GSF-8370) 64f1d3f
-* **server:** resolve from Artifactory before Maven Central (GSF-8370) (#628) f29106c
-* updating server version information for Auth [PSD-0](https://github.com/genesiscommunitysuccess/blank-app-seed/issues/0) e2f022d
-* updating server version information for Auth [PSD-0](https://github.com/genesiscommunitysuccess/blank-app-seed/issues/0) fe2dc7d
-* updating server version information for Auth [PSD-0](https://github.com/genesiscommunitysuccess/blank-app-seed/issues/0) 4204083
-* updating server version information for Auth [PSD-0](https://github.com/genesiscommunitysuccess/blank-app-seed/issues/0) 0ea031d
-* updating server version information for GSF [PSD-0](https://github.com/genesiscommunitysuccess/blank-app-seed/issues/0) 57d68e9
-* updating server version information for GSF [PSD-0](https://github.com/genesiscommunitysuccess/blank-app-seed/issues/0) 3755030
-* updating server version information for GSF [PSD-0](https://github.com/genesiscommunitysuccess/blank-app-seed/issues/0) fff92ca
-* updating server version information for GSF [PSD-0](https://github.com/genesiscommunitysuccess/blank-app-seed/issues/0) b1155f0
-* updating server version information for GSF [PSD-0](https://github.com/genesiscommunitysuccess/blank-app-seed/issues/0) 2b31d47
-* use jakarta.inject in the scaffolded EventHandlerTest (GSF-7926) 0cf7b88
-* use jakarta.inject in the scaffolded EventHandlerTest (GSF-7926) (#634) b5af5bf
+## [5.28.0](https://github.com/genesiscommunitysuccess/blank-app-seed/compare/v5.27.1...v5.28.0) (2026-10-02)
+
+
+### Features
+
+* add desktop and headless Genesis Start scripts to the client GENC-1609 2806180
+* add the AI assistant to an AI app, in a chat bubble GENC-1611 (#638) 5a04d57
+* add the AI chat panel to an AI app, loading the assistant the first time it opens GENC-1611 b6d31f5
+* always depend on the AI assistant in a React app, so a preview base already has it GENC-1611 393c84b
+* copy Create's schema 1.6.0 and cases 1.8.0, with modifies and deletes named by key GENC-1611 65f4621
+* copy to the AI config only what the seed declares its assistant reads GENC-1611 b07cf57
+* copy to the AI config only what the seed declares its assistant reads GENC-1611 (#642) 4385268
+* give an AI app the assistant package and build it with AI switched on GENC-1611 660ca45
+* keep a key only where it names a row, and check a modify's key through CI GENC-1611 c238ab3
+* move Genesis Start to 0.1.15, the first launcher that can run headless GENC-1609 81136ae
+* open the AI assistant from a chat bubble GENC-1611 212bce1
+* pass queries, references and row actions to the AI chat GENC-1611 (#643) 92d7c5e
+* pin UI 15.47.0 and pass its queries and references to the chat GENC-1611 37ebdfd
+* pin UI 15.50.0 and pass row actions and keys to the chat GENC-1611 6aafccd
+* ship the AI chat proxy with a React app that asks for it GENC-1609 4b67a7a
+* ship the AI chat proxy with a React app that asks for it GENC-1609 (#636) 76dabeb
+* write a row action's fields as the chat reads them, and check them through CI GENC-1611 fa0f782
+* write the chat panel's configuration into an AI app GENC-1611 6eff2c2
+
+
+### Bug Fixes
+
+* accept a lowercase content-type from a proxy GENC-1609 8002275
+* allow the reasoning tier's models in the proxy GENC-1609 0a9c11d
+* answer 424 when the AI key cannot be read, never an exception GENC-1609 6cdb268
+* answer the chat panel as JSON whatever it accepts GENC-1609 9c3cbb7
+* ask Google's repository only for the launcher's androidx artifacts, after Genesis's own GENC-1609 1788d9b
+* bound what the proxy will parse from a request body GENC-1609 032f00b
+* build the AI limits into the proxy so a rewritten sysdef cannot drop them GENC-1609 8144dec
+* document only the environment route for the AI keys GENC-1609 f56f8e0
+* fail the AI declaration check on a GENESIS_AI_CONSUMES it cannot use GENC-1611 35ab208
+* give each user their own assistant session and check the right on every mount GENC-1611 aedc3e3
+* hold Gemini to one candidate so the token cap is the real cap GENC-1609 f238852
+* keep a bad key and failed calls out of replies and logs GENC-1609 2da7ed6
+* keep the key out of vendor replies and bare model ids in the proxy GENC-1609 1865ad5
+* move the UI packages to 15.45.0 GENC-1611 9f85173
+* put the AI settings in the system definition the server reads GENC-1609 8082946
+* raise the router body cap above the chat proxy's 5 MiB limit GENC-1609 42d8bca
+* read the AI keys from the environment, never the system definition GENC-1609 32d5249
+* refuse a nonsense AI_MAX_OUTPUT_TOKENS instead of guessing, and never clamp below 1 GENC-1609 ae9cadc
+* refuse every model when the allow-list is empty GENC-1609 be10603
+* refuse fallback models instead of vetting them GENC-1609 a32f906
+* refuse Gemini's snake_case spellings of the capped fields GENC-1609 83401f7
+* reply through the router's stateless JSON writer GENC-1609 8bc9148
+* run chat calls outside a database transaction GENC-1609 97784a2
+* say plainly that a sent vendor call runs to completion GENC-1609 7fa161f
+* stop holding a thread for the whole vendor call GENC-1609 6ab3e9b
+* stop logging every chat request with the caller's session GENC-1609 4c1eaf9
+* use inject, not the deprecated injector, in the proxy GENC-1609 f0fae49
+* warn against requiresAuth and make the auth checks exact GENC-1609 399ea9b
 
 ## [5.27.1](https://github.com/genesiscommunitysuccess/blank-app-seed/compare/v5.27.0...v5.27.1) (2026-09-24)
 

package/README.md

@@ -1,6 +1,92 @@
 # {{appName}}
 
 {{{description}}}
+{{#if AI.enabled}}
+
+## AI chat
+
+This application includes an AI chat: an assistant in the app, and the endpoint it calls,
+`/gwf/ai-service/<vendor>/chat`, which talks to **your** AI vendor with **your** key. Nothing is
+routed through Genesis.
+
+**Set your key where the server runs, never in a tracked file in this project.** The chat endpoint
+reads it from the environment that starts the server, so set the one for your vendor there, then
+restart it (it is read once at boot):
+
+```
+AI_ANTHROPIC_API_KEY=sk-ant-...
+AI_GEMINI_API_KEY=...
+```
+
+Do not write the key into `docker-compose.yml`, which is committed with the project. Pass it through
+from the shell (`environment: [AI_ANTHROPIC_API_KEY]`) or keep it in an untracked `.env` file
+(`env_file: .env`), which the project's `.gitignore` already excludes.
+
+**Never set it as a system-definition item.** Genesis turns every `GENESIS_SYSDEF_*` variable into
+one, and writes it in plain text into the files a build or an install renders
+(`server/{{appName}}-app/build/genesis/rendered-templates/generated-system-definition.json`, and
+`generated/cfg/generated-system-definition.json` under the Genesis home, including the one under
+`build/`), into `~/.bashrc` inside the app's container, and into the logs at TRACE. So
+`GENESIS_SYSDEF_AI_ANTHROPIC_API_KEY` and `GENESIS_SYSDEF_AI_GEMINI_API_KEY`, which earlier versions
+of this app read, are refused: the endpoint logs a warning and answers as if no key were set. If you
+set one, remove it, delete the server's `build/` directory and the Genesis home's `generated/cfg`,
+and rotate the key: every copy of those files holds it. `GENESIS_ENCRYPTED_SYSDEF_...` is not read
+either.
+
+**Who can use it.** Calling the chat endpoint needs the `AI_CHAT` right. An app generated by Genesis
+Create with AI Chat selected already has it: the `AI_CHAT_USER` profile holds the right, and `admin`
+is in that profile. Add other users to that profile, or grant the right through any other profile.
+Otherwise, create the `AI_CHAT` right and grant it the same way.
+
+**The assistant.** Signed-in users get a chat bubble at the bottom right of every page, which opens
+the assistant and can be dragged out of the way. Each user gets a conversation of their own, kept until
+the page is reloaded. A user without the `AI_CHAT` right is told so in a banner when they open it,
+and the assistant sends nothing. Rights are read at sign-in, so sign in again after a change. The
+assistant can read the data this project exposes to it: which resources, and what it is told about
+each, is in `client/src/ai/generated/ai-config.json`. That folder is rewritten every time the project
+is generated, so do not edit it; add your own tools in `client/src/ai/extensions/index.ts`, which
+shows how. The client's `build` and `dev` scripts build it with `GENX_ENABLE_AI=true`; without that
+the banner says AI is switched off. Whenever the assistant is blocked, its message box reads "AI usage
+limit reached", whatever the reason; the banner above it gives the real one.
+
+**Bound what it can do.** The limits this app was generated with are built into the chat endpoint,
+`server/{{appName}}-app/src/main/genesis/scripts/ai-service-web-handler.kts`. Override either with a
+system-definition item of the same name, set from the environment as `GENESIS_SYSDEF_<name>` (they
+are not secret):
+
+- `AI_ALLOWED_MODELS` (`GENESIS_SYSDEF_AI_ALLOWED_MODELS`) lists the models a request may ask for.
+  **Set but empty, it refuses every model.**
+- `AI_MAX_OUTPUT_TOKENS` (`GENESIS_SYSDEF_AI_MAX_OUTPUT_TOKENS`) caps the output a single call can
+  request (Gemini is also held to one candidate).
+
+Fallback models and streamed replies are refused. Vendor server-side tools (for example Anthropic web
+search or Gemini Google Search grounding) are **not** filtered: anyone with `AI_CHAT` can request
+them, and they are billed to your key.
+
+**If the chat cannot answer.** With no key configured the endpoint answers **424** with the code
+`NO_API_KEY` (`BAD_API_KEY` if the key contains characters an API key cannot have). A key the vendor
+rejects, revoked or wrong, comes back as the vendor's own error, usually 401 or 400. The assistant
+tries a failed call three times in all and then shows only a generic error, so check the response in
+your browser's developer tools.
+
+**Things to know before deploying.**
+
+- For the chat, the server accepts request bodies up to 6 MiB instead of the default 256 KiB. The chat
+  endpoint itself takes up to 5 MiB, and the extra room lets it answer a turn just over that with its
+  own `REQUEST_TOO_LARGE` code. The 6 MiB limit is router-wide and applies before login, so it covers
+  every endpoint, including unauthenticated ones.
+- The app's Docker image puts nginx in front of the server, and its `nginx.conf` sets no
+  `client_max_body_size`, so nginx's 1 MiB default applies: raise it to `6m`, or chat turns over
+  1 MiB are refused before they reach the server. The Genesis Gradle plugin rewrites that
+  `nginx.conf` on every build, so don't edit it. Add a file under `/etc/nginx/conf.d/` containing
+  `client_max_body_size 6m;` instead (`nginx.conf` includes `conf.d/*.conf` inside its `http` block),
+  for example from a Dockerfile you supply through the plugin's `customDockerfile` setting, which
+  replaces the generated one. Any other reverse proxy needs the same limit.
+- The server's default CORS policy accepts any origin with credentials, and the session cookie is
+  `SameSite=Lax`. A page on the same site as this app (a sibling subdomain, for example) can therefore
+  call the chat as a logged-in user who holds `AI_CHAT`, and spend your key. Serve the app from a
+  domain nothing else shares, or restrict CORS, before exposing it.
+{{/if}}
 
 {{!
 
@@ -57,6 +143,59 @@ When first opening the project, if you receive a notification from IntelliJ IDE
 The Web client for this project can be found [here](./client/README.md). It is built using Genesis's next
 generation web development framework, which is based on Web Components.
 
+## Running the application
+
+Genesis Start runs the server for you. From `client/`:
+
+```
+npm run genesis-start            # opens the Genesis Start desktop launcher
+npm run genesis-start:headless   # the same launcher with no window, driven over a REST API on port 18080
+```
+
+On Windows, npm runs these scripts in `cmd.exe`, where `./gradlew` does not work. From `client/`, run
+`cd ..\server && gradlew.bat genesisStart` instead, adding the `-P` flags from `package.json` for
+headless.
+
+**Headless** is for a build machine or a remote development environment:
+
+- `npm run genesis-start:headless` returns once the launcher is up and prints
+  `Genesis Start started with PID <n>`. The launcher keeps running in the background, even after the
+  terminal closes, and Ctrl+C does not stop it.
+- To stop it, stop the app's processes first:
+  `curl -X POST http://localhost:18080/api/processes/application/stop-all`, then wait until
+  `curl http://localhost:18080/api/processes` shows none of them `RUNNING`, and stop any utility still
+  running with `curl -X POST http://localhost:18080/api/processes/<id>/stop`. Only then `kill <n>`.
+  Stopping the launcher first leaves every process it started running and holding its ports.
+- It takes over every Genesis process already running on the machine when it starts, so stop-all
+  stops those too, even another app's.
+- It logs to `server/build/genesis-start/output.log` and `error.log`; if it exits within five seconds,
+  Gradle says so and points there. Each process it starts logs under the app's Genesis home, and
+  `GET /api/processes/{processId}/log` returns that log.
+- Check it is up with `curl http://localhost:18080/api/health`. The API is described at
+  `http://localhost:18080/api/docs`.
+- `npm run genesis-start:write-script` writes `server/build/genesis-start/start.sh` (`start.bat` on
+  Windows), which runs the same headless launcher without Gradle, in the foreground, logging to the
+  same two files. Ctrl+C stops only the launcher, so stop the processes first, as above.
+- The script, and the command line Gradle prints as it starts the launcher (which `ps` also shows),
+  can hold the database password in plain text.
+
+**The REST API has no authentication and listens on every network interface.** Anyone who can reach
+port 18080 can:
+
+- start and stop the app's processes, and apply schema changes to its database (`/api/bootstrap`
+  runs Remap);
+- write rows into any table: `/api/import` loads files from this machine with SendIt, and a file's
+  name picks the table, so a `USER.csv` or `PROFILE_USER.csv` can add users or give them profiles,
+  and with them rights such as `AI_CHAT`. It takes a path; 0.1.15 refuses an uploaded file, but a
+  later version may not;
+- run the app's scripts with any arguments and working directory (`/api/scripts/run`), and type into
+  a running utility (`/api/processes/{processId}/input`).
+
+Run headless only on a machine and network you trust, or block port 18080 from anything else. A web
+page you visit on that machine may be able to reach `localhost:18080` too: the API checks no origin,
+and it takes JSON sent as plain text, so a page can stop or start processes and run the app's scripts
+without a CORS preflight.
+
 # License
 
 This is free and unencumbered software released into the public domain. For full terms, see [LICENSE](./LICENSE)

package/bdd-tests/build.gradle.kts

@@ -6,6 +6,7 @@ plugins {
 description = "{{appName}} BDD Testing Framework"
 
 repositories {
+    mavenCentral()
     maven {
         val repoUrl = if (properties["useDevRepo"] == "true") {
             "https://genesisglobal.jfrog.io/genesisglobal/dev-repo"
@@ -18,7 +19,6 @@ repositories {
             password = properties["genesisArtifactoryPassword"].toString()
         }
     }
-    mavenCentral()
     mavenLocal {
         // VERY IMPORTANT!!! EXCLUDE AGRONA AS IT IS A POM DEPENDENCY AND DOES NOT PLAY NICELY WITH MAVEN LOCAL!
         content {

package/bdd-tests/gradle/wrapper/gradle-wrapper.properties

@@ -1,6 +1,6 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-9.6.1-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.10.2-bin.zip
 networkTimeout=10000
 validateDistributionUrl=true
 zipStoreBase=GRADLE_USER_HOME

package/bdd-tests/gradle.properties

@@ -4,5 +4,4 @@ org.gradle.configuration-cache=false
 org.gradle.parallel=true
 org.gradle.caching=true
 bddVersion=3.5.73
-useDevRepo=true