From 7ecc1aa1c5ab3c452d48cd222aa2f4e170e499f1 Mon Sep 17 00:00:00 2001
From: delchev <delchevn@gmail.com>
Date: Thu, 27 Aug 2026 11:20:52 +0300
Subject: [PATCH] Split CLAUDE.md into topic files under .claude/docs/

CLAUDE.md grew to a single 545-line file mixing behavioral guidelines,
build/run instructions, architecture, UI gotchas, and CI reference.
Split it by topic into 18 files under .claude/docs/ and turn CLAUDE.md
into a slim index that inlines them via @-imports in the original
order, so the assembled context is byte-identical. .gitignore gets a
!.claude/docs/ entry next to the existing .claude/* exceptions so the
topic files are tracked.

Also extend the team permission allowlist in .claude/settings.json
with read-only commands observed to prompt frequently (git fetch,
gh search, mvn formatter:validate).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .claude/docs/behavioral-guidelines.md |  60 +++
 .claude/docs/blimpkit.md              |  21 +
 .claude/docs/ci.md                    |  24 ++
 .claude/docs/client-java.md           |  12 +
 .claude/docs/conventions.md           |  35 ++
 .claude/docs/document-templates.md    |  11 +
 .claude/docs/external-docs.md         |  10 +
 .claude/docs/harmonia-ui.md           |  36 ++
 .claude/docs/intent-layer.md          |  32 ++
 .claude/docs/java-debugger.md         |  46 +++
 .claude/docs/messaging.md             |  23 ++
 .claude/docs/model-generation.md      |  31 ++
 .claude/docs/native-apps.md           |   6 +
 .claude/docs/project-build-run.md     |  68 ++++
 .claude/docs/repository-layout.md     |  21 +
 .claude/docs/shells.md                |  37 ++
 .claude/docs/synchronizer-model.md    |  14 +
 .claude/docs/tenants.md               |  52 +++
 .claude/settings.json                 |   8 +-
 .gitignore                            |   3 +-
 CLAUDE.md                             | 559 +-------------------------
 21 files changed, 568 insertions(+), 541 deletions(-)
 create mode 100644 .claude/docs/behavioral-guidelines.md
 create mode 100644 .claude/docs/blimpkit.md
 create mode 100644 .claude/docs/ci.md
 create mode 100644 .claude/docs/client-java.md
 create mode 100644 .claude/docs/conventions.md
 create mode 100644 .claude/docs/document-templates.md
 create mode 100644 .claude/docs/external-docs.md
 create mode 100644 .claude/docs/harmonia-ui.md
 create mode 100644 .claude/docs/intent-layer.md
 create mode 100644 .claude/docs/java-debugger.md
 create mode 100644 .claude/docs/messaging.md
 create mode 100644 .claude/docs/model-generation.md
 create mode 100644 .claude/docs/native-apps.md
 create mode 100644 .claude/docs/project-build-run.md
 create mode 100644 .claude/docs/repository-layout.md
 create mode 100644 .claude/docs/shells.md
 create mode 100644 .claude/docs/synchronizer-model.md
 create mode 100644 .claude/docs/tenants.md

diff --git a/.claude/docs/behavioral-guidelines.md b/.claude/docs/behavioral-guidelines.md
new file mode 100644
index 00000000000..488a200ee74
--- /dev/null
+++ b/.claude/docs/behavioral-guidelines.md
@@ -0,0 +1,60 @@
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them - don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it - don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+---
+
+**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.
+
diff --git a/.claude/docs/blimpkit.md b/.claude/docs/blimpkit.md
new file mode 100644
index 00000000000..919a279af54
--- /dev/null
+++ b/.claude/docs/blimpkit.md
@@ -0,0 +1,21 @@
+## Browser UI — BlimpKit gotchas
+
+The IDE shell and most editor perspectives render through **BlimpKit**, a thin AngularJS-on-Fundamental-Styles component library that lives in `components/ui/platform-core/src/main/resources/META-INF/dirigible/platform-core/ui/blimpkit/` (Angular module name **`blimpKit`** — camelCase, declared in `blimpkit.js`). The runnable artifact is the bundled `/webjars/blimpkit__blimpkit/dist/blimpkit.min.js` (~158 KB, currently webjar 2.1.6). Findings below are the ones that have already burned someone — read once, save hours later.
+
+- **`<bk-checkbox>` is invisible without `<bk-checkbox-label>`.** `bk-checkbox` compiles to a bare `<input type="checkbox" class="fd-checkbox">`. Fundamental-Styles' `.fd-checkbox` rule hides the native input (`opacity:0; position:absolute`) on the assumption that a sibling `<bk-checkbox-label>` will draw the visible square via its `.fd-checkbox__checkmark` ::before pseudo. A lone `<bk-checkbox>` is therefore a working click target with zero visible chrome — easy to ship and never catch in code review. Pair it: `<bk-checkbox id="x" ng-model="…">` followed by `<bk-checkbox-label for="x" empty="true">…</bk-checkbox-label>` (the `empty="true"` attribute drops the inner text container so the label provides just the checkmark — use it when the surrounding markup already labels the row).
+- **`<bk-dialog>` has an isolate scope.** You can't put `ng-controller="…PopupCtrl"` on the dialog element itself — Angular throws "Multiple directives [bkDialog, ngController] asking for new/isolated scope on: <bk-dialog>". Wrap with a thin `<div ng-controller="…">` and put `<bk-dialog visible="…">` inside.
+- **`<bk-select>` doesn't support `ng-options`.** Use `<bk-option ng-repeat>` instead — text via the `text` attribute, model value via `value`. Example: `<bk-option ng-repeat="opt in items" text="{{opt.name}}" value="opt.id">`. When the select sits in a parent with `overflow:hidden` (a dialog, a sidebar), add `dropdown-fixed="true"` so the menu floats via `position:fixed` instead of being clipped.
+- **`<bk-option>`'s `text` and `value` bind differently** — `text: '@'` is **interpolation** (use `text="{{ expr }}"` or a literal), `value: '<'` is a **one-way expression** (use `value="expr"`, never `value="{{ expr }}"`). Mixing them up is the canonical bug for this directive:
+  - `value="{{s}}"` makes Angular try to parse `{{s}}` as a JS expression, the directive's link silently fails, and the dropdown shows raw `{{ text }}` from the unlinked template (one ghost item per ng-repeat iteration, not six). Fix: `value="s"`.
+  - `value="user"` evaluates `$scope.user`, not the string `"user"` — every option ends up with the same `undefined` value and selection becomes a no-op. For string literals, quote inside: `value="'user'"`. For the empty default option, `value="''"`, not `value=""` (which is the undefined-expression).
+  - Numeric literals (`value="2"`) and loop variables (`value="s"`) are already expressions — leave them unquoted. Numbers stay numbers, so `selectedValue === '2'` will fail; either store as numbers on the model or coerce in the controller (the refresh-interval dropdowns in `view-jvm-monitoring` / `view-jvm-threads` `parseInt` the model on read).
+- **Perspective SVG icons inherit `fill` from CSS — don't hard-code `fill` on the path.** `blimpkit.css` styles `.fd-list__navigation-item i.bk-icon--svg svg` with `fill: var(--fdVerticalNav_Icon_Color, #303030)` (and `var(--sapSelectedColor)` on the active state). The CSS only takes effect on `<path>` elements with **no own `fill`** — adding `fill="#000000"` (the default when you paste an SVG from a web icon set) locks the icon to black and breaks dark-theme adaptability. Strip the fill attribute (jobs.svg / operations.svg pattern) or set `fill="currentColor"` (database.svg pattern). The container svg's other niceties (`width="512"` / `height="512"` / `stroke-width=".99999"`) don't affect rendering through this CSS but are the established style.
+- **`<bk-input>` / `<bk-textarea>` / `<bk-button>` use `replace:true`.** The attributes you write on the directive element (ng-model, ng-blur, ng-keypress, ng-disabled, custom directives like `auto-focus` / `select-text`) end up on the underlying native `<input>` / `<textarea>` / `<button>`, so existing controller code keeps working unchanged after migrating native form controls to `bk-*`. ng-model binds against the parent scope — the isolate scope `bk-input` declares only owns `compact` / `state` / `glyph`.
+- **Don't put `ng-class` on a `replace:true` directive element that already has its own `ng-class`.** `bk-table-header-cell`, `bk-table-cell`, and most layout-y BlimpKit directives template as `<th ng-class="getClasses()" …>` — Angular's attribute merge **string-concatenates** duplicate `ng-class` values, producing nonsense like `ng-class="{ sorted: sort.key === 'id' } getClasses()"`. The page then throws `$parse:syntax` at compile time and the row never renders. (`class` merges cleanly — only `ng-class` is broken — so `class="no-sort"` on a `<th bk-table-header-cell>` works fine.) The fix: push the conditional class onto a child element instead of the directive root: `<th bk-table-header-cell ng-click="…"><span class="sort-caret" ng-class="{ active: sort.key === 'id' }">{{ caret() }}</span></th>`. Same applies for anything else with a `replace:true` + `ng-class` template (audit `components/ui/platform-core/.../blimpkit/*.js` for the pattern before adding `ng-class` to a `bk-*` directive).
+- **The `blimpKit` module's `.config()` block disables three `$compileProvider` flags.** `cssClassDirectivesEnabled(false)`, `commentDirectivesEnabled(false)`, and `debugInfoEnabled(false)` are flipped at module-load when debug info was on — saves per-element scope-tracking overhead in production. The last flag breaks Selenide-style debugging that calls `angular.element(node).scope()`: Angular stops attaching scope refs to DOM nodes, so the lookup returns `undefined`. If your app or its integration tests rely on that, re-enable the flags in a `.config(['$compileProvider', …])` block of your own — module config blocks run in dependency order, so `blimpKit`'s flips happen first and your override sticks.
+- **SAP-icons + the "72" body font live in platform-core's `fonts.css`.** Every BlimpKit-using page needs `<link rel="stylesheet" href="/services/web/platform-core/ui/styles/fonts.css">`. Without it `.sap-icon--*` glyphs render as tofu squares because the `@font-face { font-family: "SAP-icons"; … }` declaration is missing. The IDE shell loads this automatically via the `platform-links` injection mechanism (see below); standalone iframes (editor-bpm, embedded views) have to add the link tag explicitly. Other `@font-face` rules in the same file declare the body font: `"72"` (Regular / Light / Bold), `"72-Light"`, `"72-Bold"`, `"72Mono-Regular"`, `"72Mono-Bold"`, plus `"BusinessSuiteInAppSymbols"` and `"SAP-icons-TNT"`.
+- **`<meta name="platform-links" category="…">` auto-injects scripts + stylesheets.** Looking at any non-iframe perspective HTML you'll see a single `<meta name="platform-links" category="ng-view,ng-perspective">`-style tag in the `<head>`. `HtmlPlatformLinksInjector` (in `components/engine/engine-web/.../HtmlPlatformLinksInjector.java`) reads it at request time, walks the `category` list, and replaces the meta tag with the bundle of `<link>` and `<script>` tags registered for those categories. Categories are defined in `components/engine/engine-web/src/main/resources/platform-links.json` — `ng-view` is the heavyweight bundle (jQuery, AngularJS, all the platform hubs, BlimpKit, Fundamental-Styles, fonts.css), `ng-perspective` adds split + layout, `ng-editor` adds workspace + repository hubs, etc. Adding new shared platform code → add it to this JSON, not to every perspective HTML.
+- **`<bk-dialog>` toggles visibility via the `visible` binding, not a `.modal('show')` plugin.** `<bk-dialog visible="modal.visible">` watches the expression and adds `fd-dialog--active` when true. No backdrop element is added (the dialog's own `.fd-dialog--active` overlay handles z-index + dimming). To dismiss programmatically: flip the bound flag (`scope.modal.visible = false`) inside an `$apply`; let the directive's digest cycle remove the `--active` class; then `$timeout` ~300ms later before tearing down the scope so the close animation completes.
+- **Test selectors after a BlimpKit migration.** Native `<input class="form-control">` → `<input class="fd-input fd-input--compact">`. `<div class="modal in">` (Bootstrap-3 visible) → `<section class="fd-dialog fd-dialog--active">`. `body.modal-open` and `.modal-backdrop` are NOT set by `<bk-dialog>` — drop assertions on those, the active overlay handles its own dimming. When fixing Selenide tests that look at `.modal-header .close`, switch to `.fd-dialog__header .fd-button` (or scope to the dialog with `section.fd-dialog--active button.fd-button`).
+- **A `<split>` splitter needs the `platformSplit` module in the app's dependency list — loading the script is not enough.** The `<split>`/`<split-pane>` resizable-pane directives are defined in Angular module `platformSplit` (`platform-core/ui/platform/split.js`). The script + `split.css` are already bundled by the `ng-perspective` (and `ng-split`) `platform-links` categories, so a perspective that declares `ng-perspective` does NOT also need `ng-split`. But every app must still list `'platformSplit'` in its `angular.module('app', [...])` deps, or the directives never register: `<split>`/`<split-pane>` stay inert unknown elements and the layout collapses (one pane fills everything, the others vanish — with no console error). Working examples: `editor-csvim`, `perspective-settings`, `resources-inbox`. Layout: `.bk-split` is `height:100%`, so under a persistent `<bk-toolbar>` in a `bk-vbox` body wrap the split in `<div class="bk-stretch">` (see `resources-documents`); wrap each pane's content in `<div class="bk-vbox bk-fill-parent">`; `split-pane size` values should sum to 100; the gutter replaces any manual `bk-border--*`.
+
diff --git a/.claude/docs/ci.md b/.claude/docs/ci.md
new file mode 100644
index 00000000000..6b3a54c61d1
--- /dev/null
+++ b/.claude/docs/ci.md
@@ -0,0 +1,24 @@
+## CI reference
+
+`.github/workflows/build.yml` is the source of truth for "does this build pass" on **push to master**:
+
+- `code-style`: `mvn -T 1C formatter:validate`
+- `tests` (ubuntu + windows matrix): `mvn clean install -P unit-tests`
+- `integration-tests-h2` / `-postgresql`: the **full** Selenide IT suite, `mvn clean install -P integration-tests` with the matching `DIRIGIBLE_DATASOURCE_DEFAULT_*` env vars (MSSQL is no longer a CI leg — removed in #6150). Each DB leg is **sharded into four parallel matrix jobs** selected by tag expression — `api` (`!ui & !slow`), `ui` (`ui & !slow & !sample & !camel`), `samples` (`ui & !slow & (sample | camel)`), `slow` (`slow`) — so the run's wall clock is the slowest shard (~35 min, ~40 on PostgreSQL), not the whole ~1h40m suite. The shards partition the suite; keep them disjoint and complete when adding tags.
+- `build-deploy`: `mvn clean install -P quick-build` then Docker buildx multi-arch image push to `dirigiblelabs/dirigible`
+
+### PR gate vs full suite (smoke / nightly split)
+
+The full Selenide UI suite takes ~1.5h per DB, so it does **not** run on every PR:
+
+- **`pull-request.yml`** (every PR) runs `code-style`, unit `tests`, `docker-build`, and a single fast **`smoke-tests`** job on H2: `mvn clean install -P integration-tests -Dit.groups="!ui | smoke"`. The tag expression selects the HTTP-level ITs (untagged, so `!ui`) plus the few UI journeys explicitly marked `@Tag("smoke")` - including one full clone->generate->validate app lifecycle (`IntentEditorLoadsIT`, the intent Generate flow). Keep the smoke set small so the PR gate stays fast.
+- **`nightly.yml`** (cron `0 2 * * *` + `workflow_dispatch`) and **push to master** (`build.yml`) run the **full** suite on H2 + PostgreSQL.
+
+**Test tagging convention (JUnit 5 `@Tag`, wired to failsafe via the `${it.groups}` / `${it.excludedGroups}` properties in the root `pom.xml`):**
+- Every browser-driven IT is `@Tag("ui")` - inherited from the `UserInterfaceIntegrationTest` base (and thus by `SampleProjectsIT` and all sample-project ITs). Do not tag these individually.
+- HTTP-level ITs (`extends IntegrationTest` directly) carry no tag, so they are always in the smoke set.
+- To force a specific UI IT to run on every PR, add `@Tag("smoke")` to that class (keep the list small - smoke must stay fast).
+- Shard-routing tags: `@Tag("sample")` sits on the `SampleProjectsIT` base (inherited by every sample-project IT); `@Tag("camel")` sits on each IT in `ui/tests/camel` (their `PredefinedProjectIT` base is shared with non-camel tests, so the base cannot carry it — tag new camel ITs individually). These route classes into the `samples` CI shard; everything else UI stays in the `ui` shard.
+- `@Tag("slow")` is the **fourth shard**, and it is a *balancing* tag, not a semantic one: it holds the long poles of both families (currently the api classes above ~55 s and the browser journeys above ~110 s), because without them `api` and `ui` are the critical path while `samples` idles. Membership is a judgement about measured CI time — re-check it when the shard times drift apart, and note that mistagging can only unbalance the shards, never drop an IT (`api` is the untagged complement). It does **not** affect the PR smoke gate: a `slow` api IT is still untagged-`ui`, so `!ui | smoke` still selects it.
+
+`codeql.yml`, `release.yml` cover CodeQL and Maven Central release respectively.
diff --git a/.claude/docs/client-java.md b/.claude/docs/client-java.md
new file mode 100644
index 00000000000..de1e8fcdbd9
--- /dev/null
+++ b/.claude/docs/client-java.md
@@ -0,0 +1,12 @@
+## Client Java code (`engine-java` + `data-store-java`)
+
+Client `.java` under `/registry/public/<project>/...` is synchronized by `JavaSynchronizer`, compiled in-process (one `javac` batch + one fresh `ClientClassLoader` per generation in `JavaLoader.rebuild()`), and run through a Spring-Boot-style **bean container** (PR [#6051](https://github.com/eclipse-dirigible/dirigible/pull/6051)):
+
+- `@Component` beans with **constructor / field / collection** injection; `@Repository`, `@Controller`, `@Websocket` are meta-`@Component`. Reach platform services via the client-facing `Beans` facade (not the platform-internal `BeanProvider`).
+- **Two never-mixed handler styles** for jobs/listeners/websockets: a self-describing interface (`JobHandler.cron()`, `MessageHandler.destination()`, `WebsocketHandler.endpoint()`) **or** a method-level annotation (`@Scheduled`/`@Listener` on a `@Component` method; `@Websocket` class + `@OnX` methods). No reflective by-name fallback; the hybrid is rejected.
+- **Extension points are plain interfaces** + `@Component` contributions consumed via `List<…>` injection (or `Extensions.find`); there is no `@Extension`/`@ExtensionPoint`.
+- All client annotations/facades live in `org.eclipse.dirigible.sdk.*` (`api-modules-java`), not the old `engine.java.annotations.*`. Compile **and** bean-wiring errors surface in the IDE Problems view.
+- **Manage entities ONLY through their generated `<Entity>Repository` — never the generic `Store`/`Database` for entity CRUD.** The generated `@Repository extends JavaRepository<T>` is the sole sanctioned load/save/update/delete path; it carries validations, **event publishing** (create/`-updated`/`-deleted` topics that intent triggers/reactions/rollups/notifications consume — recorded in the tenant's `DIRIGIBLE_EVENT_OUTBOX` inside the write's own transaction, so the row and its event commit together and a broker outage neither loses the event nor fails the write; `EventOutboxRelayJob` drains what the in-process publish could not deliver), and — for `multilingual: true` entities — the **read-time translation overlay** (every find translates string properties from the sibling `<TABLE>_LANG` table for the caller's `Accept-Language`, via the SDK `org.eclipse.dirigible.sdk.db.Translator`). The name-keyed `org.eclipse.dirigible.sdk.db.Store` and raw `Database` SQL bypass all of that silently and must not touch a managed entity. (`updateWithoutEvent` is fine — a deliberate repository method that keeps validations/i18n and only omits the event, for workflow-driven system writes.) So a reusable delegate/service that must touch a *specific* entity lives **in that entity's project** (importing its repository); only entity-agnostic helpers belong in a shared project. See the engine-java guide.
+
+**Detailed guide:** [`components/engine/engine-java/CLAUDE.md`](components/engine/engine-java/CLAUDE.md). Read it before changing anything under `engine-java`, `data-store-java`, the `sdk.*` annotations, or the `*-java` templates — it covers the container, the consumers, the two handler styles + no-mixing rule, the `JavaHandler`-as-bean path, controller routing / OpenAPI / `@Roles`, `data-store-java` dynamic-map persistence, error surfacing, the **removed** internals (`RepositoryRegistry` / `RepositoryClassConsumer` / `DependencyResolver` / reflective fallback / `@Extension`), and the three-repo (platform + `dirigiblelabs/sample-java-*` + docs) sequencing.
+
diff --git a/.claude/docs/conventions.md b/.claude/docs/conventions.md
new file mode 100644
index 00000000000..d3d08114822
--- /dev/null
+++ b/.claude/docs/conventions.md
@@ -0,0 +1,35 @@
+## Conventions worth knowing
+
+- **Always write production-ready Java.** Every change must be production-grade and follow accepted Java best practices and clean-code principles — never prototype-quality, throwaway, or "good enough for now" code. This means: clear intention-revealing names; small, single-responsibility methods and classes; correct visibility and immutability (prefer `final`, avoid leaking mutable state); proper resource handling (try-with-resources); precise exception handling (no swallowed exceptions, no catch-and-ignore, fail at the right boundary); no dead code, no unused parameters/fields, no commented-out blocks; thread-safety where the runtime demands it; and defensive validation only at real system boundaries (trust internal invariants — see the global guidance against over-engineering). Favour the simplest correct design over cleverness, and keep behaviour and naming consistent with the surrounding module. Apply this standard by default to all Java in this repo without being reminded.
+- **Constructor injection only.** Every Spring bean (`@Component` / `@Service` / `@Repository` / `@Configuration` / `@RestController` / synchronizer / filter / scheduler) receives its collaborators through the constructor and holds them in `private final` fields. No `@Autowired` (or `@Inject`) on fields, no setter injection. With a single constructor, omit the redundant `@Autowired` on it. `AuthenticationInjectorRegistry` in `engine-native-apps/auth/` is the canonical example — list-typed multi-bean intake plus an immutable derived map, all in the constructor. **Documented exception:** Quartz `Job` implementations. `AutoWiringSpringBeanJobFactory.createJobInstance` instantiates jobs via `clazz.getDeclaredConstructor().newInstance()` and then calls `AutowireCapableBeanFactory.autowireBean(job)`, which only handles property/field/setter autowiring — never constructor args. `JobHandler`, the `DirigibleJob` hierarchy, and `NativeAppMonitorJob` keep `@Autowired` on collaborator fields and document the Quartz instantiation contract in a class-level comment. Do the same when adding a new Quartz Job; don't try to rewire the factory.
+- **Package-private by default.** Drop the `public` modifier from any class, interface, or enum used only within its own Java package — including its constructors and methods where the smaller surface is reachable. Cross-package use within the same Maven module still requires `public` (Java packages don't nest, so `org.eclipse.dirigible.x.auth` cannot see a package-private type from `org.eclipse.dirigible.x.proxy`). The SPI types other packages or modules extend stay `public`; the Spring-internal `@Component`s wired by other beans in the same package, helper classes, filter implementations referenced only by their router config, and DTOs consumed only by their endpoint become package-private. `engine-native-apps/proxy/*` is wholly package-private; `engine-native-apps/auth/` keeps the `AuthenticationInjector` SPI public but demotes `BasicAuthenticationInjector`. **Documented exceptions:** Quartz `Job` classes (Quartz's `Constructor.newInstance` call from `org.quartz.*` fails the language-access check on a package-private class) and Spring Data JPA repositories (Spring Data scans classpath-wide; package-private is brittle in practice).
+- **Never print to stdout or stderr - log.** No `System.out.println`, no `System.err.println`, no bare `e.printStackTrace()` anywhere in platform code. A print is invisible to the Logs view and to log aggregation, carries no level, timestamp, logger name or thread, cannot be turned down in production, and pollutes the console stream the IDE terminal shows. Use the module's SLF4J `private static final Logger LOGGER = LoggerFactory.getLogger(X.class)` at the level the event deserves (`debug` for tool output like a bundler's own lines, `warn` for a recoverable data problem, `error` **with the throwable** for a failure). In **generated / scaffolded client code** (the `template-application-*` templates, the `custom/` stubs the intent engine scaffolds) use the client SDK logger instead - `Logging.getLogger("gen.events.<module>.<Class>")` from `org.eclipse.dirigible.sdk.log` - which nests under the platform's `app.` root and shares its configuration; a generated class that prints teaches every application developer to do the same. **The one documented exception** is `ConsoleWebsocketHandler.distribute`, which is called *by* the logging appender: logging there re-enters the appender and recurses, so `System.err` is correct in that single method and the comment there says so. When in doubt, grep before you commit: `grep -rn "System\.\(out\|err\)\.print\|printStackTrace()" --include="*.java" --include="*.template" components modules | grep -v /target/ | grep -v /src/test/`.
+- **Always log the throwable.** Every `catch` block's log call must pass the exception as the trailing SLF4J argument so the stack trace lands in the log — at every level, including DEBUG. Never log only `ex.getMessage()` and drop the rest. SLF4J's parameterised form `logger.X(format, …, throwable)` treats the trailing throwable as out-of-band; the `{}` placeholder count vs. format-arg count stays balanced. Even for cases where the exception "feels expected" (an `IOException` in a daemon log pump that just means the child closed its pipe), keep the throwable so an operator who bumps the level can investigate. Skip the throwable only when there is genuinely no exception in scope (validation failures detected via `if`, not `try`).
+- **Code formatting is enforced — always run `mvn formatter:format` before every commit and push.** This is mandatory: the `code-style` CI job (`.github/workflows/build.yml`) runs `mvn formatter:validate` and fails the build on any violation, so unformatted code will not merge. Run `mvn formatter:format` (scoped to the changed module with `-pl` for speed) as the final step before staging, every time. The IDE setup (Eclipse / IntelliJ / VS Code) for importing `dirigible-formatter.xml` is documented in `CONTRIBUTING.md`.
+- **Javadoc has to compile cleanly on every Maven module that participates in the release** (anything under `components/`, `modules/`, `dependencies/`, `build/`, `tests/tests-framework`, `cli/`). The release profile attaches the `maven-javadoc-plugin:jar` execution and treats any `error:` from javadoc as fatal; the `default` profile silently skips javadoc, so problems are invisible in normal `mvn install` and only surface in `.github/workflows/release.yml`. **Run `mvn -P release -Dgpg.skip=true -DskipTests -Dlicense.skip=true -Dformatter.skip=true install` on the modules you've touched before pushing anything that adds or changes javadoc.** The recurring failure modes:
+  - **Malformed HTML from a bare `<`.** Javadoc prose is HTML — doclint parses any bare `<` as a tag start, including inside `<pre>` blocks. ASCII arrows are the classic trap: `# child field <- literal` in a `<pre>` YAML example fails as `error: malformed HTML` (broke the 2026-07-10 release via `ExpansionIntent.java`). Escape as `&lt;` (`&lt;-`), or wrap the whole example in `<pre>{@code ... }</pre>` so nothing inside is HTML-parsed. Same for `>`/`&` when ambiguous.
+  - **Unterminated inline tag.** `{@code` / `{@link` parse braces inside their argument as inline-tag delimiters. `{@code {{ }}}` — the inner `{{` opens a phantom tag and javadoc can't find the matching `}` until the next paragraph break. Escape with `<code>&#123;&#123; &#125;&#125;</code>` or rephrase to avoid braces inside braces.
+  - **`@link` reference not found.** `{@link some.external.Type}` only resolves when that type is on the javadoc tool's classpath. JUnit Jupiter, Lombok, optional-test deps and friends are typically not. Use `{@code some.external.Type}` (plain text formatting, no resolution) when the reference is purely documentation; keep `{@link …}` only for types this module compiles against.
+  - **`no comment` warning.** Add a one-liner Javadoc to every `public` member of an exported SDK class — javadoc 17+ promotes these to errors under `-Xdoclint:all`, and even today they look untidy in the published API docs.
+  Default to writing concise Javadoc on every `public` SDK / API class and method (one sentence is fine), since these are the surfaces user projects link against and the only ones whose docs get published. Internal Spring beans, IDE plumbing, and tests don't need it — comments on intent over comments on shape, per the global rule.
+- **License headers are checked.** Every Java/JS/properties file carries the EPL-2.0 header. New files should include it; `mvn license:format -P license` will add or refresh it. Most local-iteration profiles set `license.skip=true`, but the default `mvn install` does not.
+- **Integration tests boot the full Spring app and drive Chrome via Selenide.** Pass `-D selenide.headless=true` to run them on CI/headless machines. Screenshots end up in `tests/tests-integrations/build/reports/tests`.
+- **UI module resources are bundled into the `build/application` fat jar — a running instance does NOT hot-reload them.** After editing anything under `components/ui/*` or other `META-INF/dirigible/**` web resources, you must `mvn -P quick-build install -pl <module>` **and** `mvn -P quick-build package -pl build/application`, then restart `java -jar build/application/target/...jar`, before a locally running instance reflects the change. Integration tests repackage `tests-integrations` independently, so a **green IT never proves the user's running jar is current** — when a user reports "nothing changed," verify the served resource first (e.g. `curl -s -u admin:admin http://localhost:8080/services/web/<module>/...js | grep <new-token>`).
+- **DB-specific behavior is covered by parametrized CI.** `build.yml` runs the integration suite twice — H2 (default) and PostgreSQL 16 — by varying the `DIRIGIBLE_DATASOURCE_DEFAULT_*` env vars. When touching SQL or schema-emission code, replicate this locally for the affected DB rather than assuming H2 behavior generalizes. MSSQL is **no longer in CI** (removed in #6150): the SQL Server dialect + driver still ship and work for opt-in customers, but they own the `IDENTITY`/`IDENTITY_INSERT` trade-off (MSSQL uniquely rejects explicit-ID inserts into `IDENTITY` columns, which conflicts with the generated Java entity's `@GeneratedValue(IDENTITY)` path — `TableCreateProcessor` emits a plain `INT` on MSSQL). Don't assume MSSQL is exercised by any test.
+- **WebJars / `dirigiblelabs` modules.** Some IDE-side modules (names starting with `ide-`, `api-`, `ext-`) historically lived as separate repos under [dirigiblelabs](https://github.com/dirigiblelabs); per `CONTRIBUTING.md` step 8 you may need `mvn clean install -Pcontent` to pull their latest content if working across them.
+- **`*IT.java` vs `*Test.java` matters** — failsafe picks up the former, surefire the latter. Putting an integration test under a `*Test` name will silently run it during the wrong phase (and likely without the test app context).
+- **Configuration goes through `DirigibleConfig` / `Configuration`** (`modules/commons/commons-config`). When introducing a new tunable, add the enum entry there with a `DIRIGIBLE_*` env-var key and a sensible default — don't read env vars or `System.getProperty` ad-hoc.
+- **Spring beans glue everything together; `StaticObjects` is legacy.** Some code paths still grab dependencies via `StaticObjects.get(...)` (e.g. `RepositoryConfig` registers `IRepository` there explicitly) because parts of the runtime predate Spring. New code should rely on constructor injection; don't add new `StaticObjects` keys.
+- **Bean-definition overriding is enabled** (`spring.main.allow-bean-definition-overriding=true` in `application-common.properties`), so a duplicate `@Bean` name will silently shadow another. Be deliberate about bean names.
+- **JPA scan packages are `{ "org.eclipse.dirigible.components", "org.eclipse.dirigible.engine" }`** in `DataSourceSystemConfig` (both `@EnableJpaRepositories(basePackages = …)` and the `dirigible.scan.packages` property default). New artefact-bearing modules under either tree are picked up automatically; modules under other roots won't be.
+- **Cross-module FK cascades use `@OnDelete(action = OnDeleteAction.CASCADE)`.** `core-tenants` depends on `engine-security` (for `Role`), not the reverse, so a JPA-level bidirectional cascade from `Role → UserRoleAssignment` would form a module cycle. `UserRoleAssignment.role` instead carries `@org.hibernate.annotations.OnDelete(action = OnDeleteAction.CASCADE)`, which makes Hibernate emit `ON DELETE CASCADE` on the FK at schema-generation time and the DB drops the assignment row when its role is deleted. Without this, removing a `.roles` artefact whose role was still assigned to a user tripped `FK… DIRIGIBLE_USER_ROLE_ASSIGNMENTS → DIRIGIBLE_SECURITY_ROLES` and the role row survived in the DB out of sync with its missing source file. `RoleSynchronizerCleanupIT` covers it end-to-end. **Caveat for migrations:** Hibernate only emits the cascade when the FK is *created*; existing deployments keep the old un-cascading constraint until the table is rebuilt. Apply the same pattern for any new artefact-bearing entity that owns an FK to a synchronizer-managed parent.
+- **Spring Boot 3 fat-jar classpath is fragile.** Reading `BOOT-INF/lib/*.jar` resources via `ClassLoader.getResourceAsStream` — or via aggressive scanners like ClassGraph — closes pooled `NestedJarFile` handles inside `LaunchedClassLoader` and causes cascading `NoClassDefFoundError`s in unrelated platform code. If you need the platform classpath (e.g. as input to `javac --class-path`), follow `engine-java.runtime.ClassPathIndex`: open the outer fat jar with the standard `java.util.jar.JarFile`, extract `BOOT-INF/lib/*.jar` + `BOOT-INF/classes/` to a temp dir once, and use those on-disk paths. Don't introspect nested jars in-process.
+- **HTTP-driven integration tests are an option.** Most existing ITs extend `UserInterfaceIntegrationTest` and drive the IDE via Selenide — heavy and slow. For a feature you can exercise purely over HTTP, extend `IntegrationTest` instead, write fixture files directly through `IRepository.createResource(...)`, call `SynchronizationProcessor.forceProcessSynchronizers()` to trigger reconciliation synchronously, and assert via `RestAssuredExecutor.execute(callable, timeoutSeconds)` (the retry-on-AssertionError overload absorbs the small async gap between sync-return and dispatch). See `JavaEngineIT` for the pattern; it runs headless without Chrome. When the fixture is a whole project under `src/main/resources/<Name>/`, `ProjectDeployer` (tests-framework) is the shortcut: `deploy(folder)` copies it into the default user's workspace and calls the same publish endpoint the IDE's Publish button calls, `deployGeneratedFromModel(folder, "edm.model")` first calls the generation endpoint the entity modeler's Regenerate calls (reading the project's own `.gen` for the template and parameters, minus the six keys the modeler sends as request fields), and both then run the synchronizers to completion — the camel route ITs are the family that moved off Chrome this way. **Attach a `LogsAsserter` in `@BeforeEach`, never in a field initializer:** Spring re-initializes logback while it starts the application context — after the test instance is constructed — and that reset drops an appender attached any earlier, so the assertion times out against a message the log plainly shows. `forceProcessSynchronizers()` is reliable since the engine-intent PR: it used to silently no-op when the scheduled `SynchronizationJob` was mid-run (the root cause of `LocalNativeAppLifecycleIT`-style flakes); it now retries until a full pass has actually consumed the force flag (bounded at 5 minutes).
+- **Synchronizer artefact locations are registry-relative; `IRepository` paths are repository-absolute.** `SynchronizationWalker` strips the registry folder, so an artefact's `location` looks like `/myproject/file.ext` — but to read or write that file through `IRepository` you must prepend `IRepositoryStructure.PATH_REGISTRY_PUBLIC`. Code that confuses the two writes outside `/registry/public`, where no synchronizer, IT assertion, or Registry view will ever see the output (engine-intent shipped this bug once — see its CLAUDE.md "wrong turns"). The same convention shows up in `SynchronizationProcessor`'s cleanup pass and `CsvimProcessor.getCsvResource`.
+- **`JsonHelper`/`GsonHelper` exclude fields without `@Expose` — and pretty-print.** Their Gson is built with `excludeFieldsWithoutExposeAnnotation()`, so `fromJson` into a POJO whose fields lack `@Expose` silently produces an all-null object (no exception — engine-intent's parser "worked" while generating nothing). Map-shaped data is unaffected (maps aren't field-reflected). For POJO mapping either annotate every field or use a private plain `Gson`; when asserting generated JSON content in tests remember the output is pretty-printed (`"key": "value"` with a space).
+- **Windows CI fails any test that leaves a file handle open under a JUnit `@TempDir`.** POSIX deletes open files; Windows refuses, and JUnit's temp-dir cleanup turns that into "JUnit Failed to close extension context" — only on the `tests (windows)` leg, never locally on macOS/Linux. Two real burns, both in the dynamic-dependencies work: a test swapped a jar into `ModulesClassLoaderHolder` (holders deliberately never close loaders — the TEST must close the swapped `URLClassLoader` in `finally`), and a mocked `Instrumentation` captured the real `JarFile` passed to `appendToSystemClassLoaderSearch` (production keeps it open for the process lifetime by design — the test closes the captured instances in `@AfterEach` via Mockito `ArgumentCaptor`). Rule: whatever `JarFile`/`URLClassLoader`/stream a test causes to open on fixture files under `@TempDir`, the test itself must close, even when the production code's contract is to keep it open.
+- **Stale H2 files break IT runs after a killed JVM.** The file-backed H2 under `tests/tests-integrations/target/dirigible` survives a killed test run and the next context fails to load with `missing artefact with name: [DefaultDB]` or `Table ... not found (this database is empty)` cascades. `rm -rf tests/tests-integrations/target/dirigible` before re-running locally.
+- **Sample-project tests live in `tests/ui/tests/sample/` and come in FAMILIES, not one class per sample.** `SampleProjectsIT` clones a *list* of `dirigiblelabs/*` repos through the IDE Git perspective, calls `Workbench.publishAll(true)` once, runs `forceProcessSynchronizers()` + `waitForStableSynchronization()`, and does all of that once under `@DirtiesContext(AFTER_CLASS)`; each subclass then verifies one sample per `@Test`. The clone-and-publish runs in a **`@BeforeEach` guarded by the family class**, deliberately not in a `@BeforeAll` on a `@TestInstance(PER_CLASS)` class — PER_CLASS autowires the test instance *before* `@BeforeAll`, so the platform boots before `IntegrationTest.cleanBeforeTestClassExecution()` deletes the Dirigible folder and the next sync pass reaps the platform's own registry (it surfaces as "`perspective-git` not found" on a blank page, nowhere near the cause). UI-based (Selenide → Chrome), slower than HTTP-only ITs — which is exactly why the boot, the browser and the publish cycle are shared. Three subclasses: `TypeScriptSampleProjectsIT` (the TS/JS decorator samples), `JavaSampleProjectsIT` (the client-Java samples) and `SampleLibraryLocalNativeAppIT` (alone, because it spawns a real OS process). **The family split is a runtime constraint, not taste:** `sample-entity-decorators` and `sample-java-entity-decorators` both own the `SAMPLE_COUNTRY` table and both CSVIM-seed it, so they cannot be published into the same instance. Before adding a sample to a family, check it against the family for a table/route/queue/websocket-endpoint/Java-FQN collision (the whole family shares one `javac` batch and one `ClientClassLoader`), and keep the verification order-independent — the methods run against one live instance. When adding a new sample, drop the project in its own `dirigiblelabs/*` repo first, then add its URL to a family's `getRepositoryUrls()`. Inventory of sample repos under `dirigiblelabs/*`: `sample-entity-decorators`, `sample-java-entity-decorators`, `sample-roles-decorator`, `sample-job-decorator`, `sample-listener-decorator`, `sample-extension-decorator`, `sample-component-decorator`, `sample-websocket-decorator`, `sample-store-api`, `sample-intent-model`. `IntentEditorLoadsIT` is not a `SampleProjectsIT` subclass (the intent generates in the workspace, not on publish) but uses the same clone-a-real-repo pattern: it clones `dirigiblelabs/sample-intent-model`, opens its `app.intent`, and drives the editor's Generate.
+- **Spring Boot 4 strips `ResponseStatusException.getReason()`** from the default JSON error body even with `server.error.include-message=always` in `application-common.properties`. Status code reaches the client correctly; the reason text doesn't. ITs asserting 404 must check `statusCode` only, not body content (`JavaEngineIT.delete_unregisters_handler` and `compile_error_keeps_endpoint_unregistered` learned this the hard way — see commit `f13c8c219e`).
+- **The client-Java effort is split across three repositories.** The platform code (engine-java, data-store-java, IT) ships in this repo via PR [#5923](https://github.com/eclipse-dirigible/dirigible/pull/5923). The sample project that `JavaSampleProjectsIT` clones lives in [`dirigiblelabs/sample-java-entity-decorators`](https://github.com/dirigiblelabs/sample-java-entity-decorators) (initial content from PR [#1](https://github.com/dirigiblelabs/sample-java-entity-decorators/pull/1)). The announcement blog "Return of the Java – Decorators Awaken in Eclipse Dirigible" (sister piece to the December 2025 TS decorators post) goes through the docs portal in PR [`dirigible-io/dirigible-io.github.io#123`](https://github.com/dirigible-io/dirigible-io.github.io/pull/123). Follow-up Java-runtime features generally touch the same three places.
+
diff --git a/.claude/docs/document-templates.md b/.claude/docs/document-templates.md
new file mode 100644
index 00000000000..62c51923283
--- /dev/null
+++ b/.claude/docs/document-templates.md
@@ -0,0 +1,11 @@
+## Document templates (`parsers/document` + `engine-document`) — print to PDF
+
+A lightweight declarative document-template engine for printable business documents (invoice, order, receipt, ...), merged 2026-07-02 via PRs [#6118](https://github.com/eclipse-dirigible/dirigible/pull/6118) (parser library) and [#6119](https://github.com/eclipse-dirigible/dirigible/pull/6119) (platform arc). Four cooperating layers:
+
+- **`modules/parsers/document`** (`dirigible-parsers-document`, pure library, zero deps) — the XML-like DSL: hand-written parser (business-user lenient: raw `&` is literal, Mustache `{{...}}` survives verbatim, exact line/column errors), sealed `Node` AST (one record per tag + `CustomNode`/`TagRegistry.register` extension), layout primitives (`Measurement` `100/100px/50%/*/2*/auto`, `Alignment`), `DataBinder` (map-context `{{path}}` merge; `table`/`for` `source` lists expand to rows with row-scoped fallback; `if` truthiness; unresolved → empty; **`{{A|B}}` alternative operands** — first non-blank wins, left to right, the last one rendered whatever it holds, so an optional twin field never leaves a hole in a legal document; **floats print as `### ### ### ##0.00`** — the form pages' money pattern), and `XslFoRenderer` (bound layout tree → self-contained XSLT/XSL-FO stylesheet for the FOP `PDFFacade` — the platform's only PDF path). Grammar/EBNF + gotchas in the module README.
+- **`engine-intent`'s `PrintIntentGenerator`** (@Order(800)) — Generate emits a standard `<Entity>.print` per document (header-items) master at the project root; `.print` is an intent-owned (scrubbed) extension. Data contract: `{{document.<PascalProp>}}` + `<table source="items">` with `{{<PascalProp>}}` cells.
+- **`components/engine/engine-document`** — the runtime: `PrintTemplateSynchronizer` (multitenant) seeds the published template into the CMS at `Templates/<Entity>/Print/en/standard.print` **create-if-absent** — user customizations uploaded via the Documents perspective are never overwritten, and deleting the artefact never touches the CMS; `PrintEndpoint` — `GET /services/print/{entity}/languages` (CMS language folders, `Locale` display names) and `POST /services/print/{entity}?lang=` (`{document, items}` JSON → parse → bind → XSL-FO → `application/pdf`). The **client supplies the data** it already loaded (no server-side entity fetching/auth forwarding); dropdown FKs arrive as display labels.
+- **Harmonia document view** — a Print button (edit-only, footer toolbar): one CMS language prints directly, several open a language dialog ("English" → en). Multilanguage = upload templates under more `Templates/<Entity>/Print/<lang>/` folders.
+
+**Detailed guide:** [`components/engine/engine-document/CLAUDE.md`](components/engine/engine-document/CLAUDE.md). Renderer v1 limits (documented, deliberate): header/footer render once in-flow (not repeated page regions), `repeatHeader`/`pageBreak` ignored, 1px = 1pt, a data-less table is skipped (FOP rejects empty table bodies).
+
diff --git a/.claude/docs/external-docs.md b/.claude/docs/external-docs.md
new file mode 100644
index 00000000000..701fc2b1091
--- /dev/null
+++ b/.claude/docs/external-docs.md
@@ -0,0 +1,10 @@
+## External documentation
+
+The user-facing help portal at <https://www.dirigible.io/help/> documents the IDE perspectives (Workbench, Database, Git, Operations, Documents), artefact authoring (Jobs, CSVIM, Entity model, OData, Listeners, Camel routes, BPMN), JS/TS API reference (`/api/`), and deployment guides (Docker, Kubernetes, Cloud Foundry). Useful when reading integration-test fixtures under `tests/tests-integrations/src/main/resources/<TestName>/` or understanding what a given artefact extension is supposed to do.
+
+The portal is **a separate repository** — a VitePress 1.5 + Vue site built from <https://github.com/dirigible-io/dirigible-io.github.io>; that repo's own `CLAUDE.md` is the authority on its layout and rules. Doc fixes go there as PRs, not in this repo, and a merge to `master` deploys straight to www.dirigible.io via GitHub Actions. It migrated from Jekyll + six MkDocs instances in June 2026, so any guidance mentioning `docs-help/`, `mkdocs.yml`, or `blogs.json` is pre-migration and wrong. The current shape: help pages under `docs/help/**` (11 top-level sections; a new page also needs its sidebar entry in `docs/.vitepress/config.mts`), blog posts as single files `docs/blogs/YYYY/MM/DD/<slug>.md` with frontmatter (`title`, `description`, `author`, `author_gh_user`, `author_avatar`, `read_time`, `publish_date`) — the listing is generated by `docs/data/blogs.data.ts`, so no nav or index edits per post — and post images under `docs/images/<post-slug>/`, referenced relatively (`../../../../images/<post-slug>/…` from a post). House rules that bite: no em/en dashes anywhere in source (plain hyphens), VitePress admonitions (`::: tip`) not MkDocs (`!!!`), frontmatter on every page, absolute cross-links (`/help/...`), and `ignoreDeadLinks: true` masks broken links at build time — validate with `npm run docs:build` before pushing.
+
+The companion sample repos under `dirigiblelabs/*` are also separate. For end-to-end tests that clone such repos (`SampleProjectsIT` subclasses), the merge order follows the dependency direction, both ways: a dirigible-side IT that expects new sample content needs the sample-side PR merged first (else it clones an empty `master`), and a sample-side change that uses new platform APIs needs the platform PR merged first — the ITs clone the sample repo's HEAD, so merging the sample early breaks **every** PR's CI and master until the platform lands (this happened with the typed-handler interfaces: sample PR merged a day before platform PR [#6010](https://github.com/eclipse-dirigible/dirigible/pull/6010), and the Java entity-decorators verification failed across the board until #6010 merged). Re-running a failed PR check does NOT pick up a newer master — re-runs build the original merge snapshot; use `gh pr update-branch` (or push) to get a fresh merge.
+
+Treat `modules/commons/commons-config/src/main/java/org/eclipse/dirigible/commons/config/DirigibleConfig.java` (the enum) and `Configuration.java` (the allow-list) as the source of truth for env-var names and defaults, not the portal — the env-vars page lags the code by months. Specifically, the in-repo OAuth flow is Spring's `spring.security.oauth2.client.registration.github.*` activated by the `github` profile and configured via `DIRIGIBLE_GITHUB_CLIENT_ID` / `_CLIENT_SECRET` / `_SCOPE` (`build/application/src/main/resources/application-github.properties`), not the generic `DIRIGIBLE_OAUTH_*` entries some doc pages still describe. Current servlet mappings are rooted at `/services/...` and `/public/...` per `BaseEndpoint`; any `/services/v4/...` URL in a doc snippet is legacy.
+
diff --git a/.claude/docs/harmonia-ui.md b/.claude/docs/harmonia-ui.md
new file mode 100644
index 00000000000..d819a40b8d8
--- /dev/null
+++ b/.claude/docs/harmonia-ui.md
@@ -0,0 +1,36 @@
+## Harmonia runtime UI (`template-application-ui-harmonia-java` + `template-form-builder-harmonia`)
+
+The runtime UI stack for generated applications: they render as a self-contained **Alpine.js + Harmonia SPA** (client-routed by Pinecone in hash mode, no iframes/`postMessage` hubs), served at `/services/web/<project>/gen/<model>/index.html`, talking to the **reused** generated Java REST controllers over a `fetch` client. The AngularJS IDE is untouched; the application layer now ships this stack only. `template-application-ui-harmonia-java` (registered on `platform-templates` as "Application - UI (Harmonia) - Java") emits the view types (list, manage, setting, master-detail, reports) + built-in **Process Inbox** (`/inbox`) and **Documents** (`/documents`) shell sections + inline process-task surfacing; `template-form-builder-harmonia` ("Harmonia Generator from Form Model", extension `form`) is the runtime form generator. The whole stack — Alpine 3.15.11, Harmonia 2.6.0, Lucide 1.8.0 — is embedded as **webjars** via `components/resources/application-core` (report charts use Harmonia's own native `x-h-chart-*` SVG charts; the `chart.js` webjar was dropped with the AngularJS dashboard shell) (incl. Pinecone Router — `org.webjars.npm:pinecone-router`, served version-less at `/webjars/pinecone-router/dist/router.min.js`; it was vendored until the 7.5.2 webjar existed). Developed on PR [#6078](https://github.com/eclipse-dirigible/dirigible/pull/6078).
+
+**Component reference:** the full codbex-harmonia directive catalog (all `x-h-*` components incl. the `x-h-select` combobox contract, theming, layout) lives **upstream** — the docs site <https://codbex.com/harmonia/> and the agent-readable skill <https://github.com/codbex/harmonia/blob/main/skills/harmonia/SKILL.md> (formerly mirrored in-repo under `reference/harmonia/`; that copy was removed to avoid drift — always consult the upstream, version-matched to `harmonia.version` in the root `pom.xml`). [`.../reference/alpinejs/`](components/template/template-application-ui-harmonia-java/reference/alpinejs/) still covers the Alpine patterns (routing, page components), mirrored from `codbex-athena-app`, the reference app this stack was adopted from. Read them before changing Harmonia markup.
+
+**Detailed guides:** [`components/template/template-application-ui-harmonia-java/README.md`](components/template/template-application-ui-harmonia-java/README.md) (the SPA shell, view-type parity checklist, the master-detail detail registry, process-tasks store) and [`components/template/template-form-builder-harmonia/README.md`](components/template/template-form-builder-harmonia/README.md) (the neutral `formController(ctx)` contract). The repo-root [`HARMONIA_RUNTIME_PLAN.md`](HARMONIA_RUNTIME_PLAN.md) is the design doc + implementation status. **Gotchas that already burned someone — read before changing the templates:**
+
+- **REST path must use the Java-sanitised names.** `restBase` is `/services/java/<project>/gen/${javaGenFolderName}/api` and each page's `apiPath` is the **relative** `/${javaPerspectiveName}/<Entity>Controller`; the fetch client prepends `restBase` exactly once. Use `javaGenFolderName`/`javaPerspectiveName` (e.g. `sales-order` → `sales_order`), **not** the raw `genFolderName`/lowercased perspective — the generated backend lives under the sanitised Java package. (Phase 0/1 only passed because `edm` needs no sanitising.)
+- **`{ baseUrl: '' }` means "URL is absolute, prepend nothing".** The fetch client checks `opts.baseUrl !== undefined`, not truthiness — passing `''` with a relative path (or omitting it with an absolute path) is the classic doubled-URL bug (`/api/services/java/.../api/...`). Entity pages use a relative `apiPath` and **no** override; absolute URLs (relationship dropdowns, the detail registry) pass `{ baseUrl: '' }`.
+- **Date/time widgets need conversion both ways.** The form `toPayload()` turns an HTML `date`/`datetime-local` value into a full ISO instant (`…Z`) so a Jackson `java.time.Instant`/`Timestamp` field binds (empty→`null`, a bare `TIME` passes through); `toDateInput()` slices the backend's ISO value back to what the widget expects on edit. Mirrors the AngularJS stack's `new Date(value)`.
+- **Master-detail is registry-driven.** A master page renders one `detailPanel` per `App.detailsFor(<master>)` entry; each detail self-registers via `App.registerDetail(...)` (relative `apiPath`), so masters never enumerate details at generation time. The detail list filters via the controller's `?<masterEntityId>=<id>` query (built into the reused rest-java controller for `*_DETAILS` layouts).
+- **The `.form` runs the existing AngularJS `code` via compat shims, and the page is self-contained.** `template-form-builder-harmonia` runs the `.form` `code` as the body of `formController(ctx)` (`ctx.{model, params, http, task, notify, close}`) and defines `$scope`/`$http`/`NotificationHub`/`DialogHub` shims so intent-generated AngularJS `.form` code runs **unchanged** (no migration needed). The page loads only `form.js` + its own minimal fetch client (no `window.App`), because a BPM task form opens standalone in an iframe where the SPA shell assets are absent — an earlier `../../js/...` reference 404'd and left `App` undefined.
+- **A standalone page must bootstrap `App.config.projectName` before loading `i18n.js`, or every module-authored label silently stays English.** `i18n.js` reads the project namespace off `App.config.projectName` — which only the SPA shell sets — and without it fetches just the platform `application-core` chrome catalog, so the page's own `<tprefix>.t.*` keys never resolve. The failure is invisible: the baked English literals render, no console error, and every shell page around the iframe IS translated. Both standalone pages (the report page and, since [#6692](https://github.com/eclipse-dirigible/dirigible/issues/6692), the task form) therefore set it in a one-line inline script before the `<script src=".../services/i18n.js">`. Two more rules the task-form conversion paid for: a value that is MATCHED against data (a status step's `label`, compared to the record's status) stays untranslated and gets a separate translated `title`, and an authored label must be escaped where it is interpolated into a `T()` call — **both the literal and the key derived from it**, since `translationId` strips only spaces and `_ . :`, so an apostrophe would close the JS string and break the whole Alpine expression.
+- **Intent glue handlers are self-describing `@Component`s, not class-level `@Listener`/`@Scheduled`.** Those SDK annotations are `@Target(METHOD)`; the rollup/notification/integration/job templates in `template-application-events-java` were converted to `@Component implements MessageHandler/JobHandler` with `destination()`/`kind()`/`cron()` (matching the Trigger template) — class-level use fails `javac` with "annotation interface not applicable".
+- **The full-stack model template MUST merge the schema layer.** `template.js` = `template-application-schema` + REST-java + Harmonia UI. The client-Java `JavaEntityManager` only *registers* an `@Entity` against an existing table — it never CREATES one; `TableCreateProcessor` (the schema sync) does. Drop the schema and a freshly generated app has **no tables** → CRUD + CSVIM seeds fail ("Table metadata was not found for table [...]"). It only *looked* fine when a prior AngularJS/schema generation had already created them ("table kept in place").
+- **Process trigger writes its process stamp via a targeted update (no event, no full row).** Starting a process on `onCreate` writes the instance id back; doing it through the normal `update()` republishes `<entity>-updated` and spuriously fires every onUpdate reaction (e.g. the member-email notification fired the instant a loan was created) — and even the silent `updateWithoutEvent()` was a **full-row merge of the trigger's stale snapshot**, which raced concurrent writes (line items recalculating the header totals milliseconds after create, a start-step status set) and silently reverted them. The trigger writes it with one `repository.updateProperties(id, {"ProcessIds": …, "ProcessId": processId})` — an SDK `JavaRepository`/`JavaEntityStore` HQL mutation touching only the named columns; no audit stamping, no events, nothing else to clobber, while the generated repository's own bookkeeping on that path (the `history:` trail entry attributed to SYSTEM, the stored `label:` Name) still runs. What must NOT run is a gate that can REFUSE it: the generated repository skips `enforceChecks` for a targeted write that touches only **platform-owned** columns (`SYSTEM_PROPERTIES` = `ProcessId`, `ProcessIds`; `touchesAuthoredColumn(values)`), because a document check has no opinion about which process handles the record and the instance is already running by then — an unbalanced or item-less document that records its process beats one that does not. Everything a person or a workflow authors keeps the gate. **Everything that can happen before the start does**, because the stamp IS the at-most-once guard and the two commits are independent: the minted `businessKeyStrategy` value is persisted BEFORE `Process.start` (the instance is started with that key), and every process variable — the `__entityUrl`/`__entityId` locators, the FK locators, `__personalUser` — rides the **start payload** rather than a `setVariable` afterwards (they are all known up front; a process without a wait state runs to its end inside `start`, and a `setVariable` against a finished instance throws). The write-back is then the only post-start step: a `null` instance id (the platform swallows a failed start) is logged and not written, and if the write does not land — the row was deleted, or it threw — the just-started instance is **cancelled** (`Process.cancel`) and the failure re-thrown, because a running instance no record points at is invisible to the application while its user tasks still reach an inbox (#6815). The trigger guard is **per process**: `ProcessStamps.has(entity.ProcessIds, "<Process>")` over the `ProcessIds` column's `Process=instanceId` pairs (#6862). A record can legitimately be the subject of several flows — "on create, identify it; when identified, run dunning" is what the `onTransition` trigger axis invites — and the old record-wide `ProcessId != null && !isBlank()` guard made every process indistinguishable from every other, so the follow-up flow silently never started for a record the first flow had already stamped. `ProcessId` stays as the most recent instance, which is what the task UI correlates on; a `wait` and an `abortOn` read their OWN instance out of `ProcessIds` (`ProcessStamps.idFor`) instead. A record carrying only the legacy `ProcessId` counts as already handled — today's behaviour, so an upgrade cannot start a second instance of a flow that is already running. An empty string still must not count as "already started" (a form sends one for an untouched system field).
+- **Documents/CMS path contract (`/services/documents`, `engine-cms`'s `DocumentsEndpoint`).** Java since the GraalJS backend was retired — the old `/services/js/documents/api/documents.js` is **gone**, and with it the `?path=/` 400 quirk (`/` now lists the root, as does omitting the parameter). Still true: the CMS query layer does **not** decode an encoded slash, so build `?path=` with **literal slashes** — encode each segment, not the whole path (`p.split('/').map(encodeURIComponent).join('/')`); a blanket `encodeURIComponent` turns `/`→`%2F` and every subfolder/file 400s. Rename is `PUT {path,name}`; delete is `DELETE` with a JSON body of absolute paths; create a folder with `POST /folder {parentFolder,name}`; upload is multipart under the part name `file`; preview/download are `GET /preview|/download?path=`; zip is `GET|POST /zip?path=`. `__internal` is never listed or addressable (403), and `__EXPORTS` needs ADMINISTRATOR/OPERATOR. Both UIs (the AngularJS `documents/js/documents.js` perspective and the shared Harmonia `application-core/shell/.../documentsPage.js`) speak exactly this contract; content types can be overridden by contributing a `DocumentContentTypeResolver` bean (the Java replacement for the `ui-documents-content-type` extension point).
+- **Edit forms: match the value to the input shape (dates + comboboxes).** The Java REST controller serializes `java.time` via Jackson as **arrays** (`LocalDate` → `[y,m,d]`, `LocalDateTime` → `[y,m,d,h,mi,s,ns]`) and `Instant` as a **numeric epoch** — NOT ISO strings — so the form's `toDateInput()` handles arrays/numbers/strings (a naive `String(v).slice()` yields garbage → empty date controls on edit). And a relationship FK comes back as a **number** while an option's `data-value` is a string (HTML attribute), so the value must be **stringified on load** (`form.X = String(record.X)`) or the `x-h-select` matches no option and renders empty on edit — the same `String(...)` the codbex-athena-app edit pages use.
+- **Combobox = the Harmonia `x-h-select` contract; the Harmonia skill is the primary source of truth** (<https://github.com/codbex/harmonia/blob/main/skills/harmonia/SKILL.md>, version-matched to `harmonia.version` in the root pom) — existing code is only an example, and an example that contradicts the skill is wrong. `x-model` on `x-h-select-input` holds the VALUE (the option `data-value`, a string); the directive hides that input and appends a visible `button[role=combobox]` trigger (`data-slot="select-input"`) showing the matched option's label — Selenide finders and CSS target the button, and note the search's generated input also carries `role=combobox`. Use `data-filter="contains"` + an in-dropdown `x-h-select-search` for searchable pickers; options go via `x-for` with `:data-value="String(opt.value)"` **inside an `x-h-select-list`** under `x-h-select-content` — the list owns the `role=listbox`, padding and vertical scrolling (the content is `overflow-hidden`), so options placed directly in the content render clipped with no scrollbar. Clearing a selection is `data-clearable="true"` on `x-h-select` (re-clicking the selected option clears it). A `disabled` `x-h-select-input` disables the trigger with it, but the generated form still renders a **context-locked** parent FK as something else entirely (`<template x-if>` around the whole `x-h-select`) — showing the referenced record's label beats a greyed-out combobox.
+- **A parent FK implied by the navigation context renders locked, not free (#6551).** When a child is created or edited from inside its parent — a master's detail panel, a create-from flow — the opening URL names the parent FK (`?<Fk>=<id>`), and the generated manage form renders that relation as the referenced record's label, read-only (`isContextLocked(name)` / `contextLabel(value, options)` on `baseFormPage`), never as a dropdown that could re-point the record mid-flow. The shared `detailPanel` therefore carries the master FK on **edit/preview** as well as create — on edit it presets nothing (the record is authoritative), it only declares the context. A form opened with no such param (the entity's own top-level create) keeps free selection. This supersedes #6513's blanket hide of `relationshipType="COMPOSITION"`: showing which parent the record is filed under is the point; hiding the field only removed the affordance.
+- **Theme goes through Harmonia's own colour-scheme API — do not hand-toggle `.dark`.** `harmonia.min.js` manages the `.dark` class itself from `window.Harmonia.get/setColorScheme('light'|'dark'|'auto')`, persisted to localStorage key `codbex.harmonia.colorMode`; its default is `auto` (follow the OS). The shell's top-right switch (`appShell.js toggleTheme()`) calls `Harmonia.setColorScheme`, and a head bootstrap defaults the key to `light` on first run. Because **every** page loads harmonia.min.js and reads the same key, the shell and the standalone form/report iframes all theme consistently — this is why the task form no longer renders dark on a light shell (an earlier custom `dirigible.harmonia.theme` key + manual `.dark` toggle only fixed the shell, not the iframes). Settings is pinned to the **sidebar footer** (bottom-left, like codbex-athena-app); Reports is a single entry **discovered at runtime** (a `reports` store walks the project registry tree for `*/reports/*/index.html`, since intent reports are standalone pages in a separate gen folder the shell can't see at generation time). The intent recipe defaults (`IntentSettings.scaffold`) point model/form/report at the Harmonia templates; glue stays the neutral client-Java template.
+
+- **Velocity vs Alpine `$` is the #1 trap in the Harmonia shell templates.** The shell's `index.html.template` and `dashboardPage.js.template` are **generated via Velocity** (they use `$models`/`$entity`/`$appIcon`), and Velocity parses `$`-references **everywhere — including inside HTML comments and JS string bodies**. An Alpine magic like `$store`/`$notifications`/`$nextTick` is fine as a *bare reference* (undefined → Velocity passes it through literally), but the moment it's followed by a **method call with args or trailing statements** Velocity tries to parse it and the generation 500s with `Encountered "..."`. Three real burns: `$store.processTasks.openTask(n.task); n.unread=false` in an `@click` (fixed by moving the logic to an `appShell.openNotification(n)` method and calling that), `$notifications.add({ template:'toast', data:{ message, variant } })` **in an HTML comment** (Velocity choked on `{ message,…}` — reworded the comment), and `$store...filter(r => r.dashboard !== false)` in a getter (escaped via `#set($dollar='$')` + `${dollar}store`, the same trick `report.js.template` uses for `$limit`/`$nextTick`). Rule: in a Velocity-generated file keep `$store.x` to bare refs / no-arg calls, escape with `${dollar}` for anything richer, or move it into a copied (non-Velocity) JS file / an appShell method.
+- **Put cross-scope shell state in an Alpine *store*, not the `app` component.** `theme` lived on the `app` component (`x-data="app"`) and its toolbar `x-show="theme !== 'dark'"` threw **"theme is not defined" on every load** — eager `x-show` evaluation in a scope Alpine hadn't resolved yet (other `app` props on the same toolbar were fine; only the eager ones failed, intermittently). Moved it to `$store.theme` (`{ value, toggle() }`, backed by `Harmonia.set/getColorScheme`); stores resolve from any scope at any time, like `$store.notifications`/`currentUser`/`reports`/`processTasks`. (This **supersedes the `appShell.toggleTheme()` note above**.)
+- **Embedded iframes (report/form preview, task form, dashboard report tiles) only theme at load.** Harmonia applies the shared `codbex.harmonia.colorMode` key when the iframe loads; toggling the shell theme afterwards left them stale until a full refresh. Fix in **every** standalone/embeddable page — `report-file/index.html`, form-builder `ui/index.html`, **and the per-project Harmonia shell `ui/shell/index.html` itself** (it is embedded in the application-shell iframe and in the FK "Add new" dialog, and hosts the list/manage/master-detail/document views, so the one listener makes all of them follow a parent theme switch): a `storage` event listener (it fires in same-origin iframes when the **parent** changes localStorage) that calls `Harmonia.setColorScheme`. **Do NOT gate on `Harmonia.getColorScheme() !== scheme`** — it reads the same key which already holds the new value, so it always skips and nothing re-applies; track a module-level `lastApplied` scheme instead (re-apply once, no echo loop).
+- **An icon carrying an Alpine directive must be `<svg x-h-lucide>`, never `<i>`.** Harmonia refuses the combination *by throwing* — `"x-show" cannot be used on a <i> placeholder, because the element is replaced by the rendered svg and the binding would be lost` — and the exception is **not local to the icon**: it aborts the enclosing `x-for`, so every item after the first renders with no name, no id, no icon and unevaluated bindings. That is how the tenant picker (`security-oauth2/.../static/tenant-selection.html`) shipped a list that showed only its first tile, invisible until it was rendered with real data. Two corollaries from the same page: prefer `x-if` over `x-show` on an element Harmonia also styles (they fight over `display`), and give a branding logo an `@error` handler so an unresolved one hides instead of leaving the browser's broken-image glyph.
+- **`x-show` only hides — Alpine still evaluates the inner bindings.** The master-detail detail pane is `x-show="selected"`, but before a row is selected `selected` is null and `x-text="displayValue(selected.Email)"` threw `Cannot read properties of null`. Use optional chaining (`selected?.<field>`) in the property panes (list/manage/master). Same reason the report-tile preview iframes are `<template x-if>` not `x-show`.
+- **Split-panel sizing is `data-size` (a `%` or px), NOT `data-default-size`** — `data-default-size` isn't referenced anywhere in harmonia 2.1.0 (silently 50/50). Both panes need it (`data-size="60%"` + `data-size="40%"`). To collapse a pane until needed (detail-pane-until-selection), bind `:data-hidden="!selected"` on the panel — the same mechanism the sidebar's collapse uses.
+- **`x-h-toolbar-title` bakes in `whitespace-nowrap text-ellipsis overflow-hidden`** — in a flex toolbar an entity title shrank to "Bo…"/"Mem…". Add `class="shrink-0"` to entity-name titles (list/manage/master/form/report) so they keep their natural width; leave the *dynamic* inbox titles truncating.
+- **The shell is richer than the original skeleton (all model/runtime-driven):** a **home Dashboard** (`/` and `/dashboard`, `dashboardPage` + `_dashboard.html`) with report-attached KPI widget tiles (`reports[].widget`) + custom widget tiles (`widgets:`) and a per-report preview tile (the report page in `?preview=1` mode — toolbar/pagination hidden, 5 rows) — there are no auto per-entity record-count tiles; **sidebar sections** Application / Entities / **Reports** (one entry per runtime-discovered report, selecting sets `$store.reports.selected` and opens it embedded on `/reports`); a route-derived **breadcrumb** (`navLabels` from a generated `window.__harmoniaNav` map so the entity crumb matches the sidebar); and a top-right **user menu** (name from `/services/js/platform-core/services/user-name.js`, logout → `/logout`), **notifications bell** (the `notifications` store; `processTasks.syncTasks()` surfaces BPM tasks as bell items, the store polls every 30s + on `pinecone:end` so they appear without a manual refresh), and the **theme** switch. Settings still pinned to the sidebar footer.
+- **`widgetSize` is now a plain integer column count (3/4/6/12), not a Fundamental CSS class.** The entity editor stores the number; Harmonia maps it to `grid-column: span N` (12 → `col-span-full`) on a 12-col form grid. Migration caveat: old `.edm` files with the legacy `fd-col-md--2 fd-col--3` string render a broken width class.
+- **Form typography conventions (generated views).** Read-only / system fields (`isReadOnlyProperty` — `ProcessId`, audit columns, `uuid`, any `readOnly: true` field — and audit) render in a headerless **`x-h-card`** above the action buttons (a framed details block like the master-detail card, no title), NOT as editable inputs: `x-h-card` > `x-h-card-content` with a `grid-cols-1 sm:grid-cols-2 gap-x-4 gap-y-2`; each field a `vbox gap-0` with label `class="text-xs text-muted-foreground"` and value `class="text-sm"`, shown on edit and only when the value is populated. Wired in `manage/form-view` + `document/document-view` (master-detail reuses the manage form). **Document layout roles.** In a document (header-items) entity, a field with intent `documentTitle: true` → `widgetType="DOCUMENT_NUMBER"` renders in the form **title** (`'<DocLabel>'.toUpperCase() + ' ' + form.<number>`, e.g. "SALES INVOICE 00001231"), and a to-one relation with `documentStatus: true` → `widgetType="DOCUMENT_STATUS"` renders as a read-only **`x-h-badge` pill** in the title bar (text resolved from its dropdown options, colour from `statusVariant(text)` — a keyword→variant map: draft→outline, approved/accepted/active→positive, issued/sent→information, cancel/reject→negative, pending→warning). Both are pulled from the editable grid; the status keeps its dropdown lookup metadata so the pill can resolve the id→name. For secondary/muted labels (e.g. the document totals footer) use **`text-secondary-foreground`**, not `text-secondary` (the bare token is the surface colour, not the on-surface text colour — labels using it render near-invisible).
+- **The model-independent shell runtime is SHARED, not copied per project.** It lives once at `/services/web/application-core/shell/` (`components/resources/application-core/.../application-core/shell/`: `app.js`, `services/*`, `stores/*`, `components/layout/appShell.js`, base/page components, `css/app.css`, and the Inbox/Documents/Reports/notfound views). The generated per-project shell and the application shell both load it from there by absolute URL; `template-application-ui-harmonia-java` only **generates** the model-specific files (`index.html`, `config.js`, `dashboardPage.js`, `_settings.html`, `_dashboard.html`, per-entity pages). Do NOT re-add per-project copies of the shared files (`shell.js` no longer emits them). PR [#6094](https://github.com/eclipse-dirigible/dirigible/pull/6094).
+- **A BPM task's name travels with its translation key — the shell never derives one.** The Inbox, the notification bell and the app-wide task-form dialog are shared by every deployed app, so they cannot know which module's catalog holds a task's name: an Approve button stayed English on an otherwise fully translated app (#6522). So the generated `.bpmn` declares its module's catalog once, on the `<process>` element (`<flowable:property name="taskLabelCatalog" value="<project>:<model>-model.processes"/>`, minted by `IntentNaming.processTaskCatalog`), and `BpmInboxEndpoint` serves every task a `nameKey`/`processDefinitionNameKey` composed from it plus the BPMN id — which IS the authored step / process name, i.e. exactly how the catalog keys it. Read off the deployment-cached `BpmnModel`, resolved once per definition per request. Everything is decided at generation time; the client only renders `T(task.nameKey, task.name)` through the one rule on the `processTasks` store (`taskName` / `processName` / `taskLabel`) and adds the namespaces its tasks reference via `AppI18nAddNamespaces`. A process that declares no catalog (a hand-authored BPMN) keys nothing and renders the raw BPMN name, as before. **Do not reintroduce the per-project `processTaskKeys` reverse map** that `config.js` used to bake — it could only ever translate tasks from the hosting project, and two mechanisms for one label is how the shell surfaces got missed in the first place.
+
diff --git a/.claude/docs/intent-layer.md b/.claude/docs/intent-layer.md
new file mode 100644
index 00000000000..b58d5118454
--- /dev/null
+++ b/.claude/docs/intent-layer.md
@@ -0,0 +1,32 @@
+## Intent layer (`engine-intent` + `editor-intent`)
+
+A single `app.intent` YAML file at a project root is the source of truth one altitude above the model files. **The intent is an authoring artifact, not a runtime artifact** — like the `.edm` it has an editor and an explicit Generate, and (like the `.edm`) it has **no synchronizer**. Double-clicking any `*.intent` file opens the Intent Editor (`components/ui/editor-intent`): editable YAML left, live read-only diagram right (mxGraph ER + per-process flowcharts, the same engine the EDM/schema/mapping modelers use), validation inline; the Generate button runs six generators that write `.edm`/`.model`, `.bpmn`, `.form`, `.report`, `.roles` and `.csvim`/`.csv` **into the developer's workspace project at the project root** (the layout of real-world Dirigible application projects) — nothing touches the registry until normal publish, after which the per-artefact synchronizers bring the runtime live as for any project. Services: `POST /services/ide/intent/parse` and `POST /services/ide/intent/generate`. A third editor pane is a **Claude AI assistant** (`POST /services/ide/intent/agent`): it proposes the complete updated `app.intent` via the Anthropic API (key server-side in `DirigibleConfig.INTENT_AI_*`, never sent to the browser), the editor shows a Monaco diff, and Accept merges it into the buffer — the agent never writes disk or runs Generate. Developed on PR [#6017](https://github.com/eclipse-dirigible/dirigible/pull/6017). **A second assistant continues past the DSL's boundary into the Workbench** (issue [#6724](https://github.com/eclipse-dirigible/dirigible/issues/6724)): the Workbench's right-region **Assistant** view (`components/ui/view-assistant`, tracking the open editor over the layout hub) helps write the hand-written Java the model deliberately does not express (a `CalculatedField` action, a `JavaDelegate`) via `POST /services/ide/intent/assist`, proposing a complete `custom/*.java` that is **really compiled — batched with the project's other sources, as the runtime compiles it —** before the developer sees the diff, then written on an explicit Accept. It reasons about the editor's live buffer (`editor.content.request`, answered by `editor-monaco`), not the file on disk, and its conversation persists under the `workbench` surface. Both go through one shared `...intent.ai` layer (one API key, one HTTP client, one bounded repair loop); the intent agent still never emits Java and the Java assistant never touches `gen/`. **The hand-off between them is explicit**: the intent agent's proposal carries a structured `boundaries` list (issues [#6713](https://github.com/eclipse-dirigible/dirigible/issues/6713) / [#6721](https://github.com/eclipse-dirigible/dirigible/issues/6721)) — every requirement the DSL cannot express, why, and which extension point carries it — rendered as its own bubble in the Intent Editor and the Builder rather than buried in prose, and a named `calculatedAction*` gets a generate-once `custom/` stub so the boundary is a file to open. **The conversation itself IS persisted** — the one thing this module keeps in the database: a tenant-aware, append-only pair of system tables keyed by `(tenant, project, surface, path)`, read/written through `GET /services/ide/intent/conversations` + `POST .../conversations/messages` (issue [#6668](https://github.com/eclipse-dirigible/dirigible/issues/6668)), so opening an app on any machine restores the same dialogue and support can reconstruct which proposal produced which change. The intent *document* still has no table and no synchronizer — see the module guide's "Conversation store" section for the distinction and the `note`-vs-`assistant` role rule.
+
+**Detailed guide:** [`components/engine/engine-intent/CLAUDE.md`](components/engine/engine-intent/CLAUDE.md). Read it before changing anything under that module — it covers the editor-first architecture and altitude contract (model files only, never code), the YAML schema and its semantics (integer-only primary keys, `composition: true` to-one = DEPENDENT master-detail while `required` alone is just a NOT NULL FK, PascalCase property names with UPPER_SNAKE columns, decision `then`/`else`, intent-prefixed table names via `IntentNaming`), the `writeModelFile`-only write surface with the stale-output scrub, the wrong turns already made (wrong altitude, template-output paths, registry-relative vs repository-absolute paths, the `JsonHelper` Gson pitfall, **and the synchronizer-based first incarnation — do not reintroduce it**), and the follow-up list (chaining model-to-code via `.gen` descriptors, `/custom/` escape hatch). Process triggers (`trigger: { onCreate: <Entity> }`) are wired: the EDM adds a `ProcessId` field + its per-process `ProcessIds` stamps sibling + a `triggers` collection to the `.model`, and the `template-application-events-java` template generates a `gen/events/<module>/<Process>Trigger.java` listener (module-scoped package `gen.events.<module>` — two modules authoring same-named reactions no longer collide by FQN; generated beans/entities carry module-qualified names for the same reason) that starts the process on create. That persisted `ProcessId` is in turn **consumed by the generated entity-view UI**: the shared Harmonia runtime's `processTasks` store (`components/resources/application-core/.../application-core/shell/js/stores/processTasks.js`) surfaces the record's actionable BPM user tasks inline (correlating `entity.ProcessId === task.processInstanceId`), wired into every generated view gated on a `hasProcess` flag; the task form completes via the permission-checked `/services/inbox/tasks/{id}` and self-closes (#6074). `IntentEngineIT` is the HTTP-only end-to-end test (~1 minute, no sync cycles). The editor's diagram pane is **mxGraph** (replacing Mermaid, which had unfixable light/dark theming bugs) with a fixed brand-colour palette that reads on both themes — see the module guide's "Intent Editor diagram = mxGraph" section before touching `editor-intent/js/editor.js`.
+
+**Multi-model + layout additions (PRs [#6089](https://github.com/eclipse-dirigible/dirigible/pull/6089)-[#6092](https://github.com/eclipse-dirigible/dirigible/pull/6092)):** the DSL now supports building an app from **several intent models that reference each other cross-model** - a top-level `uses:` block names other models, and a relation gains an optional `model:` alias; a cross-model `manyToOne`/`oneToOne` is emitted as a read-only **PROJECTION** entity + integer FK + dropdown (the codbex cross-project pattern - no local table/DAO/controller for the target), resolved against the owner's already-generated `.model` (leaf-first generation; convention fallback otherwise). **n:m** is always an **intermediate (link) entity** (composition to one side + `manyToOne` to the other, which may be cross-model): `kind: manyToMany` **materializes** that entity at parse time (`ManyToManyExpander` — `<Declaring><Target>`, or the relation's `through: <Name>`, with a generated key + both FKs; the authored relation becomes the navigation-only `oneToMany` to it, so no generator ever sees a `manyToMany`), while a link carrying **bridge fields** like `amount` is authored explicitly and drops the `manyToMany`. The VALUE-set counterpart is **`kind: subset`** (#6878): a record holding a subset of a small lookup's rows with no data on the pairing lowers to ONE plain VARCHAR column (`"1,3"` — keys comma-separated, ascending, de-duplicated; empty = null) rendered as a Harmonia multi-select (`widgetType: MULTISELECT` + `widgetOptionsEntityName` — never `relationshipEntityName`, whose presence alone makes the schema template emit an FK); the moment the pairing needs bridge data, reverse navigation or row consumers (forEach/related/rollups/reports), it has outgrown a value — see the engine-intent guide's subset bullet. New field attributes: `unique`, `precision`/`scale`, `calculatedOnCreate`/`calculatedOnUpdate` (a neutral arithmetic expression for numeric totals, else emitted verbatim into the runtime), `calculatedActionOnCreate`/`calculatedActionOnUpdate` (server-side call-out to a hand-written `@Component implements org.eclipse.dirigible.sdk.db.CalculatedField<E,T>`, invoked as `Beans.get(<class>.class).calculate(entity)`, taking precedence over the expression — for logic too custom to model, e.g. number generation); field `readOnly: true` (not editable; rendered in the Harmonia form's read-only details block — Label:Value above the buttons — via `isReadOnlyProperty`; `ProcessId`/audit columns/`uuid` are auto-flagged read-only, `status`-style fields opt in); field `major: false` (kept off the entity **list** table — the model's `widgetIsMajor="false"` — still shown in forms + the record details pane; defaults true); entity `imports:` (Java `import` lines injected into the generated repository so a calculated action can be referenced by simple name — Base64-encoded into the `.model`'s `importsCode`, which the Java DAO template emits; the editor's entity-level Imports tab is the model-editor equivalent); entity `audit: true` (the four standard audit columns); entity `group:` (the perspective's nav-group id in the shared application shell). **Depends-On** is exposed as `dependsOn: { relation, valueFrom?, filterBy? }` on a to-one relation (cascading/narrowed dropdown) or a field (auto-populated value) — emitted as the EDM `widgetDependsOn*` attributes (the AngularJS stacks consume them as-is; the Harmonia runtime — form/document watchers + the metadata-driven item-dialog cascade — was added alongside); defaults are the respective primary keys, names are the target's authored property names, cross-model triggers/targets supported. **Multi-language data** (the TS-era `multilingual` port): entity `multilingual: true` → the schema layer generates a sibling `<TABLE>_LANG` table (`GUID, Id, <PascalCase translatable columns>, Language` — the codbex-uoms-data convention) and the generated Java repository overlays translated values on every read for the request's `Accept-Language` (SDK `Translator`, name-based merge); the supported language set is a PLATFORM concern (`DIRIGIBLE_APPLICATION_LANGUAGES`, default `en`, tenant-overridable via the tenant configuration) — the Harmonia **Region & Language** Settings entry always offers that set (an Alpine `locale` store, localStorage `codbex.harmonia.language`, sent as `Accept-Language` by the shared fetch client — one flag drives UI, data, and the Print default), while the top-level `languages: [en, bg]` only declares which languages the module PROVIDES translations for; the application shell warns about modules missing a platform language, and untranslated content falls back to the default; translations are authored as seeds with `language: bg`, and large data sets reference an authored CSV via seed `file: data/x.csv` (subfolder mandatory — root `.csv` is scrub-owned) instead of inline rows. **Related registers** (`related: [{ entity, model?, via?, label?, show? }]` on an entity, #6673) are the reverse of an incoming to-one association: the REFERENCED entity's page lists the records pointing at it (a project-month's timesheet lines, a customer's invoices, an account's journal entries), read-only, each row opening the source's own record page — declared on the referenced side because a referencing model is generated later and knows nothing about this one, filtered through the source controller's generic `POST /search` (the `?<fk>=<id>` parameter exists only on a details layout), and refused for a composition child, which is already the editable detail/items collection. **A schedule's `where` value may be a moment relative to now** (`"CURRENT_TIMESTAMP-PT30M"` / `"CURRENT_DATE+P7D"`, #6764): `<token><+|-><ISO-8601 duration>` resolved against the clock of the run that fires, which is what makes a staleness sweep expressible at all — `ScheduleSupport.Moment` is shared by the parser and the generator, a date-only amount emits a `Period` and a time-bearing one a `Duration` (`LocalDate.minus(Duration)` throws, `Duration.parse("P1M")` does not parse), and the token's shape must match the queried field's — enforced for a bare token too, so a `CURRENT_TIMESTAMP` handed to a DATE column stops being a silent never-match. A master owning an `*Item` composition child renders as the **document (header-items) layout** (`MANAGE_DOCUMENT` + `documentItemsEntity`, `uiDocumentModels`), with `aggregate: true` fields shown in the totals footer. `IntentNaming.upperSnake` collapses kebab/space/`.`/`/` separators so a hyphenated model name yields a valid SQL identifier (`sales-invoices` -> `SALES_INVOICES`). Worked example: `dirigiblelabs/sample-intent-multi-model` (six interdependent projects + a navigation-groups project).
+
+**First-class document numbering (`number:` + the `.numbers` artefact, `engine-numbering`):** a string field may declare `number: { series: Sales Invoice, per: Company, stampOn: create|issue }` — the intent references a **series by name only**; the number's shape (literal prefix + sequence zero-padded to a total width, no token grammar) lives OUTSIDE the model: declared per module in an authored **`.numbers`** artefact (`{"series": [{"name": "Sales Invoice", "prefix": "SI", "size": 10}]}`, a requirement declaration like `.roles`) and configured per tenant in the application shell's Document Numbering settings (`/services/core/numbering`). One per-tenant table `DIRIGIBLE_DOCUMENT_NUMBERS` holds shape AND counter, one row per (series, partition); the synchronizer only INSERTs missing rows, Settings writes prefix/size/next, the allocator (`sdk.numbering.DocumentNumbers.next`) increments the counter — sequences are continuous, never auto-reset, and allocating an undeclared series fails loudly. `per:` partitions a series by a to-one relation's value (per company — two legal entities never share a counter); the declaration may name the **partition source** (`"partitions": {"table", "key", "label"}` — authored physical coordinates) so Settings labels partition rows by the entity's display name and lists a VIRTUAL row per value before its first allocation (saving provisions it — seed a company's starting number before its first document). A differing cross-module re-declaration fails that artefact naming both modules; the removed `format`/`scope`/`resetOn` keys are rejected at parse. Details in the engine-intent guide's numbering bullet.
+
+**Effective-dated register lookup (`resolves:`, [#6712](https://github.com/eclipse-dirigible/dirigible/issues/6712)):** a to-one filled from the register row whose validity period covers a date the record carries — the driver from a vehicle-assignment register on the violation date, the price from the list in force on the order date, the approver from the org assignment on the request date. `resolves: - { name, event: { onCreate|onUpdate: <Record>, when? }, set: <to-one>, from: <Register>, match: { <registerProperty>: <recordProperty> }, between: { start?, end?, value }, outcome?: <string field>, found?/notFound?/ambiguous?: { setStatus } }` → a `resolves` glue descriptor → a generated `@Component MessageHandler` on the record's event topic. **All three outcomes are first-class:** exactly one covering row fills the relation, while zero and more-than-one both leave it unset — an automation that silently picks one of two candidates is worse than none, so an ambiguous register goes back to a human. Each outcome may route by `setStatus` (id or seeded name) and the attempt is observable: `outcome:` stamps `found`/`notFound`/`ambiguous` into a string field a list filter or a process `decision` can read. The copied value is derived, not authored — the register must carry exactly ONE to-one to the same target as `set:`, and zero or two is a validation error; a record that already carries the relation is skipped (a manual correction is never overwritten); the relation + outcome + status go out in ONE targeted `updateProperties`; a bound may be omitted on either side (open-ended), the end is inclusive, and a date-only bound covers its whole day. v1 is same-model and `onCreate`/`onUpdate` only. Details in the engine-intent guide's `resolves:` bullet.
+
+**The declarative state machine (`lifecycle:`, [#6714](https://github.com/eclipse-dirigible/dirigible/issues/6714)):** an entity may declare the WHOLE set of legal status edges over its `function: EntityStatus` nomenclature — `lifecycle: { edges: [{ from: DRAFT, to: [ISSUED, CANCELLED] }, ...] }`, either side a seeded name or an id — and every status write is validated against it. Until then the status machinery was point constructs (`init:`, a `transitions:` button's own guard, a workflow `setRelationField`, a check's rejection) with nothing stating which moves were legal at all, so any writer that was not a transition button could move a document from any status to any other. Enforcement is in the generated **repository** — the one choke point every writer passes through (`update`, `updateWithoutEvent`, and `updateProperties`, which the transition controller's `updateProperty` and the workflow setters route through) — rejecting an unmodeled move with 400 and a message naming both statuses; with `init:` declared, a record cannot be CREATED mid-lifecycle either. At parse time the graph is what the other status sites are held to: a `transitions:` entry's `from`→`setStatus` pair must be a declared edge (a button is presentation over the graph), and a status written by a workflow step or forced by a check must be one some edge reaches — so a reject path transiting through an approved status fails when the intent is read. There is no `on:` key (the graph is always over the EntityStatus relation, and YAML reads a bare `on` as `true`, so it is refused rather than silently dropped), and a cross-model nomenclature is declared where it is seeded. Details in the engine-intent guide's state-machine bullet.
+
+**Naming a rendered document (`fileName:`, [#6899](https://github.com/eclipse-dirigible/dirigible/issues/6899)):** the two server-side PDF renders — the snapshot copy a document mints on issue and the `attach: print` PDF a `notify` block sends — accept a **`fileName:`** pattern on the `function: Snapshot` child / inside the notify block: literals plus `{token}` interpolations, no expression language. `{field}` and one-hop `{relation.field}` use the same path vocabulary and **authored names** a notify subject does, `{field:pattern}` formats a `date`/`timestamp` through a `DateTimeFormatter` pattern, `{A|B}` renders the first non-blank operand, `{Version}` (snapshot only) places the copy's version and a pattern without it gets `_v<n>` appended. Interpolated **values** are sanitized at run time by `sdk.print.FileNames` (trim, whitespace → one `_`, path/control characters stripped, non-ASCII deliberately kept); the literal separators are the author's. A pattern's relation loads are **merged into the notify block's own**, deduped by local, so a name may read a relation the message never mentions — but `attach: recordPrint` renders the anchor once, before the per-row loop, so only fields of the anchor are readable there. Absent a pattern, the snapshot default **changes** from the old primary-key form (`Order 42 v1.pdf`) to the same number-or-id expression the mail already used, plus the version — the deliberate fix for the two names disagreeing. An unresolvable path, an unbalanced brace, a format on a non-date field or a pattern that interpolates nothing are validation errors. Details in the engine-intent guide's fileName bullet.
+
+**User-set report parameters (`reports[].parameters`, [#6357](https://github.com/eclipse-dirigible/dirigible/issues/6357)):** a report reads for a period, a threshold or a name the user chooses — `- { name: fromDate, target: issuedOn, op: ge }` renders an input above the report and binds it into the query's `WHERE`, where `target:` is a field of the source or a one-hop `relation.field` (so a parameter may filter by a column the report does not display), `op:` is `ge`/`le`/`eq`/`like` and `initial:` is the value bound when the input is empty. This is the **authoring** half only: `kind: balance` already emitted `.report` `parameters`, and the generated repository, the controller's `@QueryParam` list and the Harmonia page's parameter strip were generic over them all along. Each term is a plain binary comparison against a named marker — a structured `conditions` row, so a parameter never parks the report in the editor's free-style mode — which is why the parameter is bound on EVERY call and the neutral case rides `initial` rather than a nullable predicate: `initial` is required unless the comparison has a neutral "any value" default (a date bound, a `like` search). A **nullable** target is read through its empty value, because a plain comparison drops every row holding no value in that column the moment a parameter is declared, before the user touches anything. Details in the engine-intent guide's parameters bullet.
+
+**Mailing a REPORT (`attach: { report, bind }`, [#6931](https://github.com/eclipse-dirigible/dirigible/issues/6931)):** the report-side sibling of `attach: print`. Where a dunning reminder carries the one invoice it is about, a **customer statement** carries a period of rows - a report, not a document - so a notify block may now name a declared report and bind its `parameters:` from the recipient row: `attach: { report: CustomerStatement, bind: { customer: name, fromDate: periodStart, toDate: periodEnd } }`. `bind:` values are a field or a one-hop `relation.field` of the record the message is about (the ROW inside a `forEach`), resolved through the same resolver a `{placeholder}` uses so the relation loads are shared locals. **Every parameter that declares an `initial` must be bound** - a parameter is bound on every call (#6911), so an unbound one rides its `initial`: one FIXED slice, identical for every recipient, which is the "whole ledger to one customer" failure mode (the mail goes out, the attachment IS a report, and nothing about it says whose). A parameter with no `initial` has a neutral any-value default (a date window bound, a `like` search), so omitting it means the whole range; a balance report's own `fromDate`/`toDate` are bindable and optional for the same reason. The render goes through a **`.print` template of the report's own** - seeded once at `doc/Templates/<Report>/Print/en/standard.print` for reports something actually mails, and developer-owned afterwards like the document scaffold. It is built from the columns the `.report` pass just resolved, so every `{{alias}}` is a key the query really SELECTs, and the **bound parameters are its header**: a table of rows never states which slice it is. Since `attach` now takes a map as well as a scalar, `NotificationIntent.attach` is typed `Object` and `getAttach()` reports only the KIND (`print` / `recordPrint` / `report`). Details in the engine-intent guide's *mail a REPORT* section.
+
+**Lifecycle-aware aggregates (`stage:` + `scope:` + symbolic statuses, [#6645](https://github.com/eclipse-dirigible/dirigible/issues/6645)):** a status seed row classifies what it MEANS to the lifecycle — `stage: draft|live|cancelled|void`, metadata never emitted as a column — and a `reports:` entry declares `scope: all` or a stage name, emitted as `<alias>."<STATUS FK>" IN (<stage ids>)` ANDed onto its filter. With the nomenclature classified, an **aggregating** report **defaults to `live`** unless its dimensions/`filter` already reference the status, so a draft or voided document stops silently inflating every total (an existing model is byte-identical until it adopts `stage:`). Every site that names a status — `transitions[].from`/`setStatus`, a relation's `init:`, `setRelationField` `value:`, `abortOn.status`, a check's `status`/`setStatus`, `immutableWhen`, a posting's `event.when`, a report's `filter` — additionally accepts the **seeded name**, resolved to the id on the raw YAML tree before the typed mapping: an id is positional, so inserting a status mid-nomenclature used to silently retarget every guard authored against the old numbering (how a red-storno posting guarded on `Status == 8` stopped matching a Void that writes 9, leaving the ledger with a receivable for a document that no longer existed). A cross-model nomenclature can be neither stage-scoped nor named (its seeds live in the owner model) and says so; and when a lifecycle-carrying aggregate has neither a scope nor a status predicate nor a classified nomenclature, Generate emits a **warning** — now shown in the Intent Editor's own strip, not only the Builder shell's. Details in the engine-intent guide's lifecycle bullet.
+
+**The glue event axis: process-step events + non-HTTP inbound ([#6537](https://github.com/eclipse-dirigible/dirigible/issues/6537)):** a `notifications`/`integrations` `event:` binds either an entity lifecycle event or a **process step** — `onStepReached`/`onStepCompleted: { process, step }`. The step half adds no second delivery mechanism: `BpmnIntentGenerator` inserts a generated `JavaDelegate` at the step boundary (before the step for *reached*; after the writer/setter for *completed*, carrying the step's `next`) which loads the process's **trigger entity** by the id in the clear-D context and publishes its JSON on the entity's own topic plus a step suffix (`-step-<process>-<step>-reached|completed`), deferred to after commit — so the consumers are generated unchanged and every recipient path, `{placeholder}`, guard and forwarded body reads exactly as for a lifecycle event (`StepEventSupport` owns binding → entity → topic → emitter, deduplicated per moment). Rejected at parse: an unknown process/step, a step kind with no observable moment (only `userTask`/`serviceTask` have one), a process without a trigger. Alongside it, `inbound[]` declares **exactly one arrival** — `path:` (the `@Controller` webhook), `source: { queue | topic }` (a self-describing `MessageHandler`), or `source: { folder, cron }` (a `JobHandler` polling the drop folder: one record or an array per file, a file touched in the last few seconds is left for the next tick, every read file moves to `processed/`/`failed/`). All three save through the same generated repository — the arrival is a transport, not a second data path; a folder is polled, never watched, hence the mandatory cron there and its rejection elsewhere. **Mapping on arrival ([#6769](https://github.com/eclipse-dirigible/dirigible/issues/6769)):** deserializing the payload straight into the entity only works when it already *is* the entity, so an arrival may declare `accept: { type, version }` — a gate whose misses are **acknowledged and ignored** with a warning (202 on a webhook), never failed into redelivery — and `map:`, projecting envelope keys onto the record's own, where a value may be `{ lookup: <Entity>, by: <uniqueField>, from: <envelopeKey> }` resolving a **business key to a relation** (the requirement that alone forced a hand-written consumer). A non-unique `by:` is refused at Generate (it would silently pick one of several rows) and a lookup matching nothing **rejects** the arrival rather than storing a null FK; `ArrivalSupport` pre-renders the gate and each typed conversion, both keys work on all three arrivals, and omitting them generates byte-identically. **The departure half ([#6767](https://github.com/eclipse-dirigible/dirigible/issues/6767)):** `outbound[]` binds the same axis and emits on a queue or a topic — `to:` names exactly one of `queue`/`topic`, `payload:` is the same declared envelope `integrations:` takes, and the generated `<Name>Publisher.java` is a `MessageHandler` **subscribed to the record's own event topic** that re-publishes through `sdk.messaging.Producer`; because it is a subscriber the write is already committed, so a failed publish is logged and never fatal (no outbox, no exactly-once, no ordering — stated, not implied). The destination name is passed to the platform verbatim, so a departure inherits the `global:` external-contract marker ([#6766](https://github.com/eclipse-dirigible/dirigible/issues/6766)): unmarked names stay application-owned and tenant-prefixed, a `global:` one addresses another deployment.
+
+**The enrichment channel (`phases:` + `onPhase`, [#6929](https://github.com/eclipse-dirigible/dirigible/issues/6929)):** a value a listener computes AFTER the insert — a moving-average cost, a snapshot column, an external lookup — must be written back **event-silently** or it re-fires every onUpdate consumer of a change the user never made; so it published nothing at all, and a declarative consumer of that value had no moment to bind. Bound to `onCreate` it RACED the enrichment (two listeners on one topic have no order — each `MessageHandler` is its own durable subscriber, and there is no priority anywhere), and posted a balanced-looking journal entry for a null amount with parse, generation, compile and publish all green. The fix is a CHANNEL, not an ordering contract the broker cannot keep: an entity declares the moments it announces (`phases: [costed]`), the Java DAO template emits one **`announce<Phase>(id, values)`** per phase — `updateProperties` with the phase's own topic, so the enrichment and its notice ride ONE write into the outbox and commit together — and any glue consumer binds `event: { onPhase: <Entity>, phase: <name> }`. The generated method is the point: a hand-typed topic string reproduces exactly the silence being removed, a mistyped `announceCosted` is a compile error. Accepted by `postings:` (the driver), `notifications:`, `integrations:`, `outbound:` and an event-driven `generates:`, with the `when:` guard optional there (the phase already IS one moment); deliberately not by a process `trigger:`, a `wait` or `resolves:`. Refused at parse, each because it is otherwise silent: a phase that is not a lower-camel identifier, one named after a platform channel (`updated`/`deleted`/`transitioned`/`rekeyed`), a duplicate, a `phase:` key on another axis, and a binding naming a phase the entity does not declare. Details in the engine-intent guide's phases bullet.
+
+**Event-driven create-from (`generates` + `event:`, [#6711](https://github.com/eclipse-dirigible/dirigible/issues/6711)):** a `generates` entry may declare `event: { onTransition: <from>, when: "<Status> == <status>" }` (guard mandatory) or `{ onCreate: <from> }` and mint the follow-up **document — header AND items** by itself when the source reaches a state, instead of waiting for the button (`posts` is event-driven but emits flat rows and cannot reference the new header). The `map` entry copying the source's key IS the back-reference and therefore the **at-most-once** guard, derived rather than declared twice; the button is dropped unless `button: true`, and both triggers share ONE generated create-from (a new `GenerateOnEvent.java.template` listener calls `<X>Generate.create(id)` and carries no mapping of its own). Details in the engine-intent guide's `event:` bullet.
+
+**Declarative step resilience (`retry:` / `onError:` / `{error}` / `vars:`, [#6762](https://github.com/eclipse-dirigible/dirigible/issues/6762)):** a `delegate:` service task may declare `retry: { count, every }` (a Flowable failed-job retry cycle, `R<count+1>/<every>` — the R number counts TOTAL attempts) and `onError: <step | end>` (an error boundary event routed like a decision branch). The boundary only fires on a `BpmnError`, so `engine-bpm-flowable`'s `ResilientClassDelegateFactory` converts the FINAL failed attempt (mirroring `JobRetryCmd`'s arithmetic) into the caught `INTENT_STEP_FAILED` error, publishing the failure message as the `__errorMessage` variable — which a `setField` step on the error route reads via the whole-value `{error}` token. Process-level `vars:` + step `produces:`/`uses:` declare step data (an undeclared name is a parse error) and `clearAfter: <step>` removes a value — a generated credential — from the instance data once that step completes. v1 is delegate-only (parser-enforced); absent keys generate byte-identically. Details in the engine-intent guide's step-resilience bullet.
+
+**The general platform line this enshrines:** authoring artifacts (`.edm`, `.model`, `.form`, `.report`, `.intent`) get **workspace editors + an explicit Generate**; only runtime artifacts (`.roles`, `.bpmn`, `.csvim`, `.table`, jobs, listeners, …) get **synchronizers**. Applying the synchronizer hammer to an authoring artifact generates into the registry where no modeler, Projects view, or template can use it — that mistake was made once and reverted; the inventory of synchronizers (grep `extends BaseSynchronizer`) deliberately contains no authoring formats.
+
diff --git a/.claude/docs/java-debugger.md b/.claude/docs/java-debugger.md
new file mode 100644
index 00000000000..0076b647f96
--- /dev/null
+++ b/.claude/docs/java-debugger.md
@@ -0,0 +1,46 @@
+## Java Debugger (`ide-java-debug` + `view-java-debug`)
+
+Implemented in PR [#5948](https://github.com/eclipse-dirigible/dirigible/pull/5948). Bridges the browser IDE to a JDWP-enabled JVM via the Debug Adapter Protocol (DAP).
+
+### Architecture
+
+```
+Browser (debug.js) ←WebSocket→ JavaDebugWebSocketHandler
+                                  ↓ JavaDebugManager
+                                  ↓ JavaDebugBridge (per workspace)
+                                  ↓ DAP TCP socket
+                                  JDT.LS (vscode.java.startDebugSession)
+                                  ↓ JDWP TCP (port 8000 by default)
+                                  Target JVM
+```
+
+**Key classes:**
+- `JavaDebugManager` (`components/ide/ide-java-debug`) — singleton Spring bean; one `JavaDebugBridge` per `username/workspace` key. `getOrStart()` is the entry point: asks JDT.LS for a DAP TCP port via `workspace/executeCommand → vscode.java.startDebugSession`, then creates the bridge. `removeSession()` tears down the bridge when the last WebSocket session leaves.
+- `JavaDebugBridge` — reads Content-Length-framed DAP messages from the TCP socket and broadcasts them as raw JSON to all WebSocket sessions. Translates `setBreakpoints` source paths from virtual workspace paths (`/workspace/proj/Foo.java`) to real filesystem paths before forwarding to the DAP server. **`destroy()` sends `disconnect` with `terminateDebuggee:false` before closing the socket** — without this the DAP adapter calls `VM.exit()` and kills the JVM, making the JDWP port refuse the next attach.
+- `JavaDebugWebSocketHandler` — Spring WebSocket handler at `/websockets/ide/java-debug?workspace=<name>`. On open: `manager.getOrStart(username, workspace).addSession(session)`. On message: `bridge.sendToDap(json)`. On close: `manager.removeSession(sessionId)`.
+- `JavaDebugConfigEndpoint` — `GET /services/ide/java-debug/config` → `{"jdwpPort": N}`. The default port is `DirigibleConfig.JAVA_DEBUG_JDWP_PORT` (`DIRIGIBLE_JAVA_DEBUG_JDWP_PORT`, default `8000`).
+
+**OSGi requirement:** `com.microsoft.java.debug.plugin-*.jar` must be in the JDT.LS `plugins/` directory **and** listed in every `config_<platform>/config.ini` `osgi.bundles` entry. `JdtLsManager.installDebugPlugin()` handles both — it reads `Bundle-Version` from the jar's manifest and appends the entry. Without this, `vscode.java.startDebugSession` returns "unknown command".
+
+**Path translation:** the browser sends virtual paths like `/workspace/proj/Foo.java`; the DAP server needs real paths like `/home/user/.dirigible/repository/root/users/admin/workspace/proj/Foo.java`. `JavaDebugBridge.translateSourcePaths()` rewrites `setBreakpoints` requests. In the reverse direction, `realToVirtualPath()` in `debug.js` uses `lastIndexOf('/' + workspaceName + '/')` to strip the server prefix from stack-frame source paths.
+
+**Server-side LSP init:** `JdtLsInstance.ensureInitialized()` sends `initialize` + `initialized` to JDT.LS without a browser editor session so that `workspace/executeCommand` is not queued forever waiting for a client. Timeout: 60 s for `ensureInitialized`, 90 s for `startDebugSession` (CI runners are slow).
+
+### Frontend (`components/ui/view-java-debug`)
+
+- **Region:** `left` (sits alongside Projects/Import/Search in the left sidebar)
+- **Config:** `configs/debug-view.js` — `region: 'left'`, `lazyLoad: true`
+- **Layout:** compact toolbar (Attach, Disconnect, step controls) + status strip + three collapsible sections (Call Stack, Variables, Breakpoints)
+- **Workspace:** read from `localStorage[${getBrandingInfo().prefix}.workspace.selected]` on load; kept in sync via `platform.workspace.changed` hub topic (same source as the Projects view)
+- **Port:** fetched from `GET /services/ide/java-debug/config` on startup; falls back to 8000
+- **Host:** always `localhost` — not configurable from the UI
+- **Connecting animation:** `$interval` cycles through 18 descriptive phrases every 3 s while `status === 'connecting'`; cancelled on connected / error / disconnect / terminate / `$destroy`
+- **Breakpoints persistence:** stored in `localStorage['dirigible.java.debug.breakpoints']` as `{ virtualPath → int[] }`. Restored on load; `refreshBpList()` must be called after restoring to populate `$scope.bpList`.
+
+### Editor integration (`components/ui/editor-monaco`)
+
+- **`java.debug.highlight` topic:** `debug.js` posts `{ filePath: realPath, lineNumber }` when paused; editors match via `filePath.endsWith(myPath)`. Post is repeated after 1500 ms for newly opened tabs. `clearPausedState()` in `dapContinue()` posts `{ filePath: null, lineNumber: 0 }` immediately (the DAP `continued` event is optional and often skipped by the Java adapter for long-running JVMs).
+- **`java.debug.breakpoints` topic:** `debug.js` broadcasts the full `breakpoints` map; each editor restores glyph decorations for its own path. After registering its listener the editor immediately posts `java.debug.breakpoints.request` so the debug view re-broadcasts — this handles the race where the debug view's startup broadcast fires before the editor iframe is ready.
+- **Glyph CSS** (`editor.css`): `.debug-breakpoint-glyph` — red circle (14 × 14 px, `border-radius:50%`). `.debug-current-line-glyph` — right-pointing yellow triangle (CSS border trick, `#ffcc00`, 12 × 14 px). `.debug-current-line` — faint yellow line background.
+- **Glyph margin clicks:** `onMouseDown` with `isGlyphMarginLineNumber` toggles breakpoints and posts `java.debug.breakpoints.changed` with the updated lines array for that file.
+
diff --git a/.claude/docs/messaging.md b/.claude/docs/messaging.md
new file mode 100644
index 00000000000..24c388beb32
--- /dev/null
+++ b/.claude/docs/messaging.md
@@ -0,0 +1,23 @@
+## Messaging perspective (`ide-messaging-monitoring` + `perspective-messaging`)
+
+A devops/debug surface for the embedded ActiveMQ broker — **embedded mode only**, see the broker-mode note below. Three modules cooperate:
+
+- **`components/ide/ide-messaging-monitoring`** — backend service + REST endpoint. Constructor-injects the `BrokerService` bean from `engine-listeners` (the broker is started with `useJmx=false` in `EmbeddedBrokerMessagingConfig`, so JMX is unavailable — read state directly off the bean instead). Both the service and the endpoint are `@Conditional(EmbeddedMessagingBrokerCondition.class)` — **with an external broker there is no `BrokerService` bean, so neither is registered and every endpoint here answers 404** (an external broker is administered from its own console). `RegionBroker.getDestinationMap()` enumerates queues and topics; `Destination.getDestinationStatistics()` exposes the counters; `Destination.browse()` returns the in-memory pending set without consuming. Endpoints live under `/services/ide/messaging-monitoring/` with `@RolesAllowed({ADMINISTRATOR, DEVELOPER, OPERATOR})`:
+  - `GET /summary` — broker meta + every queue/topic with counters
+  - `GET /queues/{name}/messages?limit=N` — non-destructive browse (capped at 200 by default, body preview at 64 KB)
+  - `DELETE /queues/{name}/messages` — purge
+  - `DELETE /queues/{name}/messages/{messageId}` — remove a single message
+  - `DELETE /queues/{name}` and `DELETE /topics/{name}` — remove the destination (returns 409 if consumers are still attached — `IllegalStateException` translated by the endpoint)
+- **`components/ui/perspective-messaging`** — perspective shell (id `messaging`, order 1010), icon, menu, extensions.
+- **`components/ui/view-messaging-destinations`** (left) and **`components/ui/view-messaging-browser`** (center) — filterable list of destinations and master-detail message inspector. They communicate over `MessageHub` topics `messaging.destination.selected` (selection broadcast), `messaging.destination.selection.request` (browser asks destinations view to re-broadcast on init — fixes the iframe-startup race), and `messaging.broker.refresh` (browser asks destinations view to re-poll after a mutating action). Confirm-dialogs go through `DialogHub.showAlert({type:'confirmation', buttons:[...]})`.
+
+**Topic limitation:** JMS topics do not retain non-persistent messages, so the browser shows live counters but no message list for topics. Message-body decoding prefers `ActiveMQTextMessage.getText()`; for `BytesMessage`-style payloads, the first 64 KB are inspected and rendered as UTF-8 when they look textual, otherwise base64-encoded.
+
+**Broker mode — embedded or external** (`engine-listeners/.../listeners/config/`). Set `DIRIGIBLE_MESSAGING_BROKER_URL` (plus optional `DIRIGIBLE_MESSAGING_BROKER_USERNAME` / `_PASSWORD`) and the platform stops starting its own broker and connects to that one instead — `tcp://`, `ssl://`, `failover:(…)`, e.g. Amazon MQ or a dockerized ActiveMQ shared by several deployments. Unset (or blank) keeps the previous behaviour exactly: an in-process `BrokerService` reached over `vm://localhost`.
+
+The two modes are two `@Configuration` classes — `EmbeddedBrokerMessagingConfig` and `ExternalBrokerMessagingConfig` — selected by `EmbeddedMessagingBrokerCondition` / `ExternalMessagingBrokerCondition`, which are the exact negation of one another, so exactly one always applies. Three things are worth knowing before touching this:
+
+- **The conditions read `DirigibleConfig`, not the Spring `Environment`** — deliberately, and this is the repo's only hand-written `Condition`. Dirigible resolves a key across its own layers and a value placed there programmatically (`Configuration.set`, which is how `ExternalMessagingBrokerIT` selects the mode) never reaches the `Environment`, so `@ConditionalOnProperty` would not see it. Conditions evaluate once per context refresh: an integration test must set the config in a static `@BeforeAll`, before the context is created.
+- **Both modes define the `ActiveMQConnection` and `ActiveMQSession` beans**; only the embedded one defines `ActiveMQBroker`. Nothing else changes, because every consumer — the `.listener` artifacts, the client-Java listeners (`engine-java`'s `ListenerClassConsumer`), `MessagingFacade` — reaches the broker through `ActiveMQConnectionArtifactsFactory`, which resolves the `ActiveMQConnectionFactory` **by type**. Swapping that one bean is the whole change; do not reintroduce a `@DependsOn("ActiveMQBroker")` outside the embedded config.
+- `DIRIGIBLE_MESSAGING_USE_DEFAULT_DATABASE` configures the embedded broker's persistence only and is logged as ignored in external mode. Anything else that reaches for the `BrokerService` bean must tolerate its absence (`ObjectProvider`, as `CloseActiveMQResourcesApplicationListener` does) or be conditional on the embedded mode (as the monitoring component is). An unreachable external broker fails startup on purpose.
+
diff --git a/.claude/docs/model-generation.md b/.claude/docs/model-generation.md
new file mode 100644
index 00000000000..a3297f8e5e5
--- /dev/null
+++ b/.claude/docs/model-generation.md
@@ -0,0 +1,31 @@
+## Model-to-code generation is Java (`ide-template`)
+
+Turning a model file into generated artefacts — the "Generate from EDM / model" step every template
+rides on — runs entirely in Java, in `components/ide/ide-template`
+(`ModelGenerationService` → `ModelGenerator` / `GlueGenerator` / `ModelParameterProcessor` /
+`ModelTemplateAdapters` / `ModelTemplateRenderer`). The endpoint is
+**`POST /services/ide/generate/model/{workspace}/{project}?path=<model>`** with body
+`{template, parameters}`; the older JavaScript path (`generate.mjs` + `generateUtils.js` +
+`parameterUtils.js` under `service-generate`) was migrated and **deleted** — see
+[`GENERATION_UTILS_JAVA_PLAN.md`](GENERATION_UTILS_JAVA_PLAN.md) §6-§7. Things to know before touching it:
+
+- **Template descriptors are still JavaScript.** Each `template-*` module exports `getTemplate()`
+  (sources + parameters), which the Java pipeline reads through
+  `GenerationService.getTemplateMetadata` (a GraalJS call per template). Their `generate()` functions
+  are gone: the per-template pre-logic lives in `ModelTemplateAdapters`, keyed by template id, and a
+  template the pipeline does not know is **refused by name** rather than half-generated. Add a
+  template → add its adapter entry.
+- **Every number in the parameter graph is a `Double`** and an absent key is not a null one
+  (`ModelValues.putNumber` / `remove`) — the graph reaches the engines through a `Map` deserialization
+  that types every JSON number as `Double`, so `minLength` renders as `0.0` and always did.
+- **Write JSON with `JavaScriptJson`, not Gson**, for the `.gen` descriptor and the translation
+  catalogs: Gson drops null keys, escapes HTML and writes `6.0` where the descriptor needs `6`.
+- **The Mustache engine writes into the parameter map it is handed** (it adds an indexed twin of every
+  collection), so `ModelTemplateRenderer` copies the context per invocation. Without that, the
+  artefacts land in the `.gen` descriptor, which is re-read on the next regeneration and accumulates.
+- **The intent Generate is one call**: `IntentGenerationService` writes the model files and then runs
+  the `.settings` recipes through this pipeline itself, reporting each one's outcome in
+  `codeGenerations` (`generated`, plus `error`). No client replays a plan any more.
+- `ModelGenerationIT` is the regression harness (it replaced the JS-vs-Java parity harness): every
+  template renders, twice, with the descriptor and the cross-project entity extension asserted.
+
diff --git a/.claude/docs/native-apps.md b/.claude/docs/native-apps.md
new file mode 100644
index 00000000000..7987d531e6b
--- /dev/null
+++ b/.claude/docs/native-apps.md
@@ -0,0 +1,6 @@
+## Native applications (`engine-native-apps`)
+
+User projects can declare a `*.nativeapp` JSON file that turns an external web server — local OS process or remote HTTP(S) endpoint — into a first-class Dirigible artefact, reverse-proxied under `/services/native-apps-proxy/v1/<basePath>/...` with optional Dirigible-managed authentication and role-based access. The whole feature lives in `components/engine/engine-native-apps`.
+
+**Detailed guide:** [`components/engine/engine-native-apps/CLAUDE.md`](components/engine/engine-native-apps/CLAUDE.md). Read it before changing anything under that module — it covers the synchronizer model, kinds + start modes, port resolution, the stop / teardown contract (three layered guarantees), the dual-DELETE rehydrate requirement, PID + port logging, the proxy filter chain, placeholder expansion, the credentials field naming, the management endpoint's role policy, integration-test patterns including the no-manual-cleanup rule, and the macOS gotchas (Python 3.14 bind regression, wildcard-vs-loopback `ServerSocket` probe, `PollingWatchService` deadlock).
+
diff --git a/.claude/docs/project-build-run.md b/.claude/docs/project-build-run.md
new file mode 100644
index 00000000000..792f935ab58
--- /dev/null
+++ b/.claude/docs/project-build-run.md
@@ -0,0 +1,68 @@
+## Project
+
+Eclipse Dirigible — a high-productivity application platform (hpaPaaS). The runtime is a single Spring Boot fat jar that bundles an in-browser IDE plus execution engines (GraalJS, Flowable BPM, Camel, Quartz, Lucene, CMS, OData, etc.). It supports "In-System Programming": users develop and modify the running system through the browser. The shipped artifact is `build/application/target/dirigible-application-*-executable.jar`; the entry point is `org.eclipse.dirigible.DirigibleApplication` (`build/application/src/main/java/org/eclipse/dirigible/DirigibleApplication.java`).
+
+## Prerequisites
+
+- Java JDK 21 (project compiles to Java 21; CI builds/tests run on Corretto 24, bytecode target stays 21)
+- Maven 3.8.x
+- Node.js 22.x with global installs of `typescript` and `esbuild` (frontend WebJars are transpiled/bundled at build time)
+- `ttyd` (only required at runtime for the in-IDE terminal on port 9000, and for integration tests)
+
+## Build
+
+The whole project is a multi-module Maven build at the root. The Maven coordinates are `org.eclipse.dirigible:dirigible-parent` (currently `14.0.0-SNAPSHOT`).
+
+| Goal                                | Command                                                            |
+| ----------------------------------- | ------------------------------------------------------------------ |
+| Full build with all unit tests      | `mvn clean install`                                                |
+| Fast build (no tests/javadoc/license/format) | `mvn -T 1C clean install -P quick-build`                  |
+| Unit tests only (no ITs)            | `mvn clean install -P unit-tests`                                  |
+| Run unit + integration tests        | `mvn clean install -P tests`                                       |
+| Integration tests only              | `mvn clean install -P integration-tests -D selenide.headless=true` |
+| A specific IT (comma-separated)     | `mvn clean install -P integration-tests -Dit.test="CsvimIT,CreateNewProjectIT" -D selenide.headless=true` |
+| A specific unit test (single module) | `mvn -pl <module-path> -am test -Dtest=ClassName#method`          |
+| Format Java code                    | `mvn formatter:format` (or `-P format`)                            |
+| Validate formatting (what CI runs)  | `mvn -T 1C formatter:validate`                                     |
+| Static analysis                     | `mvn clean install -P spotbugs`                                    |
+| Coverage report (JaCoCo)            | `mvn clean -B package -P coverage`                                 |
+| Update license headers              | `mvn license:format -P license -DskipExistingHeaders=false`        |
+
+The Java formatter profile is `dirigible-formatter.xml` at the repo root — CI fails the build on formatter violations, so run `mvn formatter:format` (or rely on the IDE save action configured per `CONTRIBUTING.md`) before pushing.
+
+Tests follow Maven's surefire/failsafe split: `*Test` runs under surefire (unit), `*IT` runs under failsafe (integration). Integration tests are Selenide-based UI tests living in `tests/tests-integrations/src/main/java/.../tests/`. The build profile `integration-tests` disables surefire and only runs failsafe.
+
+## Run
+
+After a build:
+
+```
+java -jar build/application/target/dirigible-application-*-executable.jar
+```
+
+UI at `http://localhost:8080`, default credentials `admin`/`admin`. Useful URLs on the same port:
+
+- `/` — redirects to the IDE entrypoint (default `services/web/shell-ide/`, configurable via `DIRIGIBLE_HOME_URL`)
+- `/swagger-ui/index.html`, `/api-docs` — OpenAPI / Swagger UI for built-in REST endpoints
+- `/spring-admin/` — Spring Boot Admin (server profile enabled in this app)
+- `/actuator/health/readiness`, `/actuator/health/liveness` — health probes (also what the CI DAST job polls)
+- `/services/...` — secured Spring-side endpoints (see `BaseEndpoint.PREFIX_ENDPOINT_*`)
+- `/public/...` — unauthenticated counterpart
+- `/services/js/<project>/<file>.{js,mjs,ts}` — execute a JS/TS file from the user repository (the same path under `/public/js/` is the unauthenticated variant)
+- `/odata/v2/...` — OData services (CXF base path)
+- `/websockets/...` — WebSocket endpoints
+
+Default DB is **file-backed** H2 at `jdbc:h2:file:./target/dirigible/h2/DefaultDB;LOCK_TIMEOUT=10000` (see `components/data/data-sources/src/main/resources/META-INF/dirigible/datasources/DefaultDB.datasource` — this is also why `mvn clean` is required when switching DBs, the old H2 files survive otherwise). Switch by exporting `DIRIGIBLE_DATASOURCE_DEFAULT_DRIVER/URL/USERNAME/PASSWORD`. Server port is overridable via `DIRIGIBLE_SERVER_PORT` (default 8080). The in-IDE terminal launches `ttyd` on 9000. The Dockerfile additionally exposes 8081 as the Graalium debug port (env var `DIRIGIBLE_JAVASCRIPT_GRAALVM_DEBUGGER_PORT`; debugging is on by default via `DIRIGIBLE_GRAALIUM_ENABLE_DEBUG=true`).
+
+The on-disk Dirigible repository ("registry") defaults to `./target/` relative to the working directory (`DIRIGIBLE_REPOSITORY_LOCAL_ROOT_FOLDER`). Inside it the canonical layout is `/registry/public/<project>/...` for published artefacts and `/users/<user>/workspace/<project>/...` for in-IDE workspaces (see `IRepositoryStructure`). Multi-tenancy is on by default (`DIRIGIBLE_MULTI_TENANT_MODE=true`).
+
+For remote debugging:
+
+```
+java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8000 -jar build/application/target/dirigible-application-*-executable.jar
+```
+
+## Local dev-loop automation (`.claude/` commands + script)
+
+The repo ships Claude Code slash commands (`/dirigible-start`, `/dirigible-stop`, `/dirigible-logs`, `/dirigible-test`, `/dirigible-pr` in `.claude/commands/`) wrapping one cross-platform Node.js driver (`.claude/scripts/dirigible.mjs`) for the local build/run/log/test/PR loop. Prefer these over hand-running `mvn`/`java`. **Maintainer reference (read before changing the commands or driver): [`.claude/scripts/README.md`](.claude/scripts/README.md)** — driver subcommands, cross-platform mechanics, the background-task log-tail rationale, and the team-wide permission whitelist in `.claude/settings.json`. The user-facing guide is the "Claude Code Commands" section of the root `README.md`.
+
diff --git a/.claude/docs/repository-layout.md b/.claude/docs/repository-layout.md
new file mode 100644
index 00000000000..ab1c3ba399d
--- /dev/null
+++ b/.claude/docs/repository-layout.md
@@ -0,0 +1,21 @@
+## Repository layout
+
+The Maven hierarchy (from root `pom.xml`) is: `modules`, `components`, `build`, `dependencies`, `tests`, `cli`. Each is a Maven aggregator.
+
+- **`modules/`** — low-level platform building blocks consumed by everything else: `commons`, `database`, `engines` (script engine abstractions), `odata`, `parsers`, `repository`. These are pure libraries with no Spring wiring.
+- **`components/`** — the Spring application surface, split by concern. The `build/application` module wires all of these together via Spring Boot auto-configuration — there is no manual "list of features"; capability comes from whichever components/* JARs are on the classpath.
+  - `components/core/` — base Spring infrastructure: `core-base`, `core-configurations`, `core-database`, `core-extensions`, `core-initializers`, `core-registry`, `core-repository`, `core-spring`, `core-tenants`, `core-tracing`, `core-version`, `core-healthcheck`, `core-project`.
+  - `components/engine/` — runtime execution engines: `engine-java` (client `.java` runtime — synchronizer + compiler + SPI; see "Client Java code" below), `engine-javascript` (GraalVM polyglot), `engine-typescript`, `engine-bpm-flowable` (workflows), `engine-camel` (integration routes), `engine-jobs` (Quartz), `engine-listeners` (message listeners), `engine-cms-*` (internal / S3 / SharePoint), `engine-odata`, `engine-openapi`, `engine-web`, `engine-websockets`, `engine-template-*`, `engine-open-telemetry`, etc. Each engine registers itself as a Spring component and contributes routes/processors/scheduled jobs to the running app.
+  - `components/api/` — Java implementations of JS/TS APIs that user code in the IDE can `import` (e.g. `api-database`, `api-http`, `api-mail`, `api-git`, `api-bpm`, `api-cms`, `api-s3`, `api-kafka`, `api-rabbitmq`, `api-mongodb`, `api-pdf`, ...). These are bridged into GraalJS by `engine-javascript`.
+  - `components/data/` — data-layer tooling: `data-sources`, `data-structures` (HDB-style table definitions), `data-management`, `data-import`/`-export`, `data-csvim` (CSV import model), `data-store` (TS `@Entity` decorators → Hibernate via HBM XML), `data-store-java` (Java `@Entity` annotations → same Hibernate machinery; consumes `engine-java`'s SPI), `data-transfer`, `data-processes`.
+  - `components/ide/` — the browser IDE: a large set of `ide-ui-*` WebJar modules (Monaco, perspectives for git/bpm/database/jobs/etc.) plus backend services `ide-git`, `ide-terminal`, `ide-workspace`, `ide-console`. Frontend assets are bundled with `esbuild`/`tsc` during the Maven build, hence the Node toolchain prerequisite.
+  - `components/platform/`, `components/platform-ide/`, `components/security/`, `components/template/`, `components/ui/`, `components/resources/` — perspective/branding/security plumbing and shared UI assets.
+  - `components/group/` — _Maven aggregators only_ (`group-api`, `group-engines`, `group-ide`, ...). When you add a new component module, register it in the matching `group-*/pom.xml` so the assembly picks it up.
+- **`build/application/`** — the only thing that turns the above into a runnable jar. `DirigibleApplication.java` is intentionally small (just `@SpringBootApplication` + `@EnableAdminServer` + Camel OpenTelemetry). `Dockerfile` lives here too.
+- **`tests/tests-framework/`** — shared Selenide/Spring test base classes used by ITs.
+- **`tests/tests-integrations/`** — `*IT.java` UI integration tests plus project fixtures under `src/main/resources/<TestName>/`. Each IT fixture directory is a Dirigible project that gets imported and exercised through the running app.
+- **`cli/`** — standalone helper that starts the Dirigible jar against a given user project path; produces `cli/target/dirigible-cli-*-executable.jar`. See `cli/README.md`.
+- **`maven-plugins/flowable-bpmn-docs-maven-plugin/`** — custom Maven plugin generating BPMN docs.
+- **`dependencies/`** — BOM-style module aggregating third-party version pins (the actual `<properties>` for versions still live in the root `pom.xml`).
+- **`open-telemetry/`**, **`samples/`**, **`misc/`**, **`npm/`** — auxiliary content, not part of the Maven reactor in the root build (verify in the relevant `pom.xml` before assuming).
+
diff --git a/.claude/docs/shells.md b/.claude/docs/shells.md
new file mode 100644
index 00000000000..4945f55a1f1
--- /dev/null
+++ b/.claude/docs/shells.md
@@ -0,0 +1,37 @@
+### Application shell (`resources-application`) — the pure-Harmonia app launchpad
+
+`components/resources/resources-application` (`dirigible-components-resources-application`), served at **`/services/web/application/`**, is the shell **for the application layer** — the IDE stays AngularJS + BlimpKit, but the app layer is pure Java + Harmonia (the AngularJS Dashboard shell it replaced, `resources-dashboard`, was removed in #6589). It reuses the shared runtime for the built-in Dashboard/Inbox/Documents/Reports pages (Pinecone routes into `#app`) and aggregates the **`application-perspectives`** extension point for the domain apps, hosting each one's generated SPA in an embedded iframe (`?embedded`). It shows **named perspective groups only**, so the platform's AngularJS *utility* perspectives (e.g. `platformSettings` → `/services/web/perspective-settings/settings.html`, `ng-app="settings"`) are excluded — **never iframe an AngularJS perspective into the Harmonia shell, it won't bootstrap standalone**. Each generated app contributes one per-entity perspective to `application-perspectives` whose `groupId` is the intent entity's `group:`; the groups are defined once in a dedicated navigation-groups project (the codbex pattern). Wired into `components/pom.xml` (modules + dependencyManagement) and `group-ui`.
+
+**A perspective the aggregator cannot place is never dropped, and never silently** (issue [#6646](https://github.com/eclipse-dirigible/dirigible/issues/6646)). `platform-core/extension-services/modules/perspectives.mjs` pushes perspectives into groups **by `groupId`**; an id matching no group used to be discarded, so the group rendered empty — indistinguishable from "no module contributes here", with no console warning and no log line anywhere (the *authored-but-silently-unconsumed* class). Now: the unmatched id is `console.error`-ed naming the perspective and the id, then placed in the extension point's **default group** — a group declaring `isDefault: true` — else the platform's `undefined-group` catch-all, else handed back standalone for the shell to render. The **single-group shells** (`resources-personal` / `resources-partner` / `resources-admin`) declare their one group `isDefault: true`, so their generated perspectives (`ui/{my,partner,admin}/*-perspective.js.template`) deliberately declare **no `groupId` at all** — repeating a platform constant in every generated artifact is a coupling that can only drift, and the "My Work" → "Personal" rename proved it: every already-generated module kept `groupId: 'my'` and its personal pages vanished. `undefined-group` is deliberately **not** marked default, so a no-`groupId` perspective on `application-perspectives` still comes back standalone and the shells' catch-all "Other" section renders it (that branch now rescues **any** `kind`, not just `PRIMARY` — enumerating kinds is how `PERSONAL` fell off the end of the chain). `PerspectiveGroupAggregationIT` guards both placements; `IntentEmissionCoverageIT` asserts the perspective is **inside** its group, not merely present in the response.
+
+### Builder shell (`resources-builder`) — the conversational AI intent builder
+
+`components/resources/resources-builder`, served at **`/services/web/builder/`** (shell id `builder`, `.access`-gated to ADMINISTRATOR/DEVELOPER), is a standalone Harmonia shell where you **describe an application in plain language and publish it**. It adds **no backend**: it is a frontend orchestration over endpoints that already ship, reusing the shared `application-core` runtime (theme/notifications/branding/i18n) by absolute URL. One screen, so there is deliberately **no Pinecone router**.
+
+The loop: chat → `POST /services/ide/intent/agent` → **re-validate the proposal client-side through `POST /parse`** → auto-apply (no diff/Accept — the chat text is the narration) → the canvas redraws. **The agent answers 200 even when its proposal still fails validation** (the server's two repair rounds were exhausted, signalled only as trailing prose in `reply`), so the client-side re-validation is load-bearing, not belt-and-braces — an invalid proposal is shown as issues and never reaches the buffer. Project and file management are hidden: the project id is a slug of the intent's `name`, created lazily on the first accepted proposal and never renamed; every accepted proposal is auto-saved, so a reload restores from disk. Chat history is persisted **server-side** per `(tenant, project, surface)` and restored on open (the agent endpoint is stateless, so the transcript is a record the platform keeps, not browser state); the store appends one turn at a time and a failed append is carried by the next turn rather than breaking the chat.
+
+**The one button** (`js/services/pipeline.js`, the `publish` store) runs save → **Problems baseline** → `/intent/generate` (which generates the models AND the code from them in that one call, reporting each recipe's outcome in `codeGenerations`) → publisher → healthcheck poll + **Problems diff filtered to `/<project>`**. That diff is the only honest "published clean" signal — publishing is synchronous but reports nothing about what the synchronizers made of the artefacts, so a client-Java compile error or a failed CSVIM seed surfaces there and nowhere else. The success panel's "try it here" links are **discovered** (`platform-shells`, plus the app's own perspective path from `application-perspectives`) — never assembled from a guessed `gen/<model>` convention, which would 404 the moment a template changed its layout.
+
+Gotchas this shell paid for (all confirmed by `IntentBuilderShellIT`):
+- **Never put an Alpine binding on `<i x-h-lucide>`.** The plugin REPLACES the `<i>` with the rendered svg, so a binding would be lost — it throws instead, and the uncaught throw **aborts Alpine's walk over everything below it** (the toolbar rendered, the whole split pane did not). Use an `<svg x-h-lucide>` placeholder for any `:data-lucide` / `:class` / `x-show`.
+- **The idempotent creates answer `304`, and `response.ok` is 2xx-only.** `POST /workspaces/{ws}` and `.../{ws}/{project}` return 201 the first time and **304 NOT MODIFIED** afterwards, so a naive `!response.ok` throw makes the *second* save fail while the first succeeded. The fetch helper takes an `alsoOk: [304]`.
+- **The workspace may not exist at all** on an instance where the user never opened the IDE; creating a project inside a missing workspace answers 404, so `ensureProject` creates the workspace first.
+- The agent endpoint can make three upstream calls at 120s each — the client timeout is **7 minutes**, with a staged typing indicator.
+- **Ask `GET /services/ide/intent/agent/status` whether the assistant is usable, never a throwaway `/agent` turn.** The shell probes on load so an unconfigured instance says so before the user types; the status endpoint reads configuration only, so it costs no upstream model call (a probe that posted a real turn would burn an Anthropic round-trip on every page load of a *working* instance).
+
+The mxGraph rendering is **shared, not copied**: `editor-intent/js/intent-diagrams.js` exposes the framework-free `window.IntentDiagrams.render(model, host)` / `.dispose(host)`, extracted from the Intent Editor's controller and loaded by both (the shell by absolute URL). A standalone page must link **`platform-core/ui/styles/fonts.css`** or the glue cards' SAP-icon glyphs render as tofu. Tests: `IntentBuilderShellIT` — a `@Tag("smoke")` bootstrap check plus the full journey against a **local HTTP stub of the Anthropic upstream** (`DIRIGIBLE_INTENT_AI_BASE_URL`, the same override `IntentAgentServiceTest` uses in-process), so it needs no key and no network.
+
+### Monitoring shell (`resources-monitoring`) — the operations surface
+
+`components/resources/resources-monitoring`, served at **`/services/web/monitoring/`** (shell id `monitoringShell`, order 37, icon `activity`, gated to ADMINISTRATOR/OPERATOR/DEVELOPER by `monitoring.access`), answers "is the system healthy, and if not, what broke?" without opening the IDE. Same skeleton as `resources-my` / `resources-admin`: a pure-resources module over the **shared** runtime at `/services/web/application-core/shell/`, **no new backend** — every page reads an existing, role-gated platform endpoint. Six pages: **Overview** (health, readiness, artefacts in error, failed jobs, process incidents, DB-pool pressure, broker backlog — polled every 30 s, pausable), **Processes** (instances + the live BPMN diagram + the two triage actions, retry/skip), **Jobs** (list, execution log with the tenant column, enable/disable/trigger), **Logs** (the `/websockets/ide/console` live stream + the log files), **Messaging** (read-only), **System** (the build this instance runs + the JVM snapshot + session-local sparklines). Design docs: repo-root `MONITORING_SHELL_PLAN.md`; delivered on PRs [#6613](https://github.com/eclipse-dirigible/dirigible/pull/6613) (backend prerequisites), [#6614](https://github.com/eclipse-dirigible/dirigible/pull/6614) (shell + Overview) and [#6615](https://github.com/eclipse-dirigible/dirigible/pull/6615) (the remaining pages).
+
+Things worth knowing before changing it:
+
+- **The scope line is deliberate.** Deep and destructive tooling — SQL console, terminal, message purging, process-variable editing, tracing, **log-level changes** — stays in the Workbench permanently; each page links there instead of cloning it. Re-implementing a BPMN modeler or a data grid here means we overshot.
+- **Two backend prerequisites shipped with it** (#6613): `HttpSecurityURIConfigurator` now carries a **monitoring gate** (`/services/bpm/bpm-processes/**`, `/services/ide/{monitoring,logs,loggers,messaging-monitoring}/**`, `/websockets/ide/console`) matched **before** the DEVELOPER gate, aligning the URL layer with those controllers' declared `@RolesAllowed` — the rest of `/services/ide/**` and `/services/bpm/**` (workspaces, git, publisher, the BPMN modeler) stays DEVELOPER-only, and `HttpSecurityURIConfiguratorTest` guards the whole matrix including the ordering. And `GET /services/core/artefacts` (`ArtefactStatusEndpoint` in `core-base`) aggregates the `ArtefactService` beans — every synchronizer registers one, so the bean list *is* the inventory; it replaces depending on the IDE perspective's `artefacts.mjs` JS aggregator.
+- **Every read goes through `js/services/ops.js`**, and the aggregate pages wrap each source in `ops.soft(...)` so one unavailable engine degrades to a marked tile instead of an empty screen. The Overview's incident scan is one request per active instance (there is no bulk endpoint) and is capped at 50 — the page says so rather than silently reporting "no incidents".
+- **The BPMN diagram is the same visualizer the IDE uses** (`bpmn-visualization` webjar), loaded on first use (~1 MB — the Overview must not pay for it) and themed through Harmonia's own `--foreground` / `--input-background` / `--positive` / `--negative` variables. The server-side PNG endpoint stays a fallback: it is static and theme-blind.
+- **Known data issues, filed but not blocking:** job logs leak and clear across tenants ([#6606](https://github.com/eclipse-dirigible/dirigible/issues/6606)), tracing reads/deletes are cross-tenant ([#6607](https://github.com/eclipse-dirigible/dirigible/issues/6607)), `TracingFacade.disableTracing()` sets the flag to `"true"` ([#6608](https://github.com/eclipse-dirigible/dirigible/issues/6608)), `JobEndpoint.emailremove` is doubly broken ([#6609](https://github.com/eclipse-dirigible/dirigible/issues/6609)). v1 is an instance-level operator surface and shows the job-log tenant column until #6606 lands. The BPM/Flowable queries **are** tenant-filtered — no issue there.
+- **"Which build is this?" is answered from `/services/core/version`** — the same payload the Workbench's About window reads, in the `version` store (read once; a running instance never changes its build), rendered as the System page's **Build** card and condensed onto the sidebar footer, where every page shows it. The keys behind it (`DIRIGIBLE_PRODUCT_NAME` / `_VERSION` / `_COMMIT_ID`) ship **unfiltered** in `dirigible-commons.properties`, so until `build/application/src/main/resources/dirigible.properties` re-declared them (that module filters its resources and runs the git-commit-id plugin) every stock instance reported the literal `${project.version}` and the About window hid the row. A downstream distribution overrides the same three keys with its own `dirigible.properties`; the UI treats a value that still looks like a Maven placeholder as unknown.
+- **`MonitoringShellIT`** (`@Tag("ui")`) is the guard that matters: the Alpine-bootstrap failure mode (an Alpine binding on an `<i x-h-lucide>` aborts the walk) has no DOM or server-side symptom, so only a real browser catches it. Each page root carries a stable id (`monitoring-<page>-page`) so the assertions do not depend on what happens to be deployed.
+
diff --git a/.claude/docs/synchronizer-model.md b/.claude/docs/synchronizer-model.md
new file mode 100644
index 00000000000..181542ed0e7
--- /dev/null
+++ b/.claude/docs/synchronizer-model.md
@@ -0,0 +1,14 @@
+## How a feature reaches the running system (the synchronizer model)
+
+This is the single most important architectural pattern to understand before changing engines or adding artefact types. Dirigible does not "deploy" projects — instead, files in the repository (`/registry/public/...`) are continuously reconciled into runtime state by **synchronizers**.
+
+Each artefact type has three collaborating pieces:
+
+1. An **Artefact** JPA entity (`extends Artefact` from `components/core/core-base`) — the persisted projection of a file.
+2. A **Synchronizer** (`extends BaseSynchronizer<A, ID>` or `MultitenantBaseSynchronizer`) — registered as a Spring bean, scans the repository for a specific file extension/pattern, parses it, upserts the artefact, and reacts to lifecycle phases (`CREATE`, `UPDATE`, `DELETE`, `START`, `STOP`). Ordering across synchronizer types is fixed in `SynchronizersOrder`.
+3. An optional **engine/service/endpoint** that consumes the live artefact (e.g. Quartz scheduler for jobs, Flowable for `.bpmn`, Camel for routes, Spring MVC endpoints for `expose` declarations).
+
+Existing synchronizer implementations (grep `extends BaseSynchronizer` / `extends MultitenantBaseSynchronizer`) give a complete inventory of supported artefact types: `Job`, `Bpmn`, `Camel`, `Listener`, `Csvim`, `DataSource`, `Table`, `View`, `Access` (security), `Expose` (URL routing), `ExtensionPoint` / `Extension`, `Markdown`, `Proxy`, `PrintTemplate` (`.print` → CMS seeding), etc. Adding a new artefact type means producing a new synchronizer + entity + (usually) a service, then registering it in the relevant `group-*` aggregator.
+
+JS/TS user code is **not** synchronized — it is loaded on demand by `engine-javascript` (`JavascriptEndpoint` at `/services/js/...`, `/public/js/...`) via `DirigibleJavascriptCodeRunner` backed by Graalium/GraalVM polyglot. The `api-*` Java modules under `components/api/` register the JS-callable APIs (`@dirigible/db`, `@dirigible/http`, etc.) into the GraalJS context — pre-built TS/JS bundles for those APIs live in `components/api/api-modules-javascript/src/main/resources/META-INF/dirigible/modules/`.
+
diff --git a/.claude/docs/tenants.md b/.claude/docs/tenants.md
new file mode 100644
index 00000000000..f88e859c237
--- /dev/null
+++ b/.claude/docs/tenants.md
@@ -0,0 +1,52 @@
+## Tenant resolution strategy (`core-tenants` + `core-base`)
+
+How the current tenant of a request is determined is configurable through `DIRIGIBLE_TENANT_RESOLUTION_STRATEGY` (`TenantResolutionStrategy` in `core-base`, read once per `TenantExtractor` instance, i.e. at context refresh):
+
+- **`SUBDOMAIN`** (default, unchanged behaviour) — the subdomain of the `host` / `x-forwarded-host` header is matched against `DIRIGIBLE_TENANT_SUBDOMAIN_REGEX` and looked up by subdomain. A host naming no registered tenant is answered with the 404 written by `TenantContextInitFilter`. Every tenant needs its own host.
+- **`TOKEN_GROUPS`** — the tenant is the one the user selected, read from the HTTP session attribute `TenantSelectionConstants.SELECTED_TENANT_ID_SESSION_ATTRIBUTE` and required to be `PROVISIONED`. The host is never consulted, so one host serves every tenant. No session, no selection, an unknown selection, or a tenant that is not provisioned yet all fall back to the **default tenant** — machine-to-machine calls and anonymous requests carry no session, and a stale selection must not lock a user out.
+
+`TOKEN_GROUPS` exists for deployments where authorization is carried in identity provider groups named **`<tenantId>.<appId>.<role>`** (e.g. `acme.library.Owner`). `TenantGroupsParser` (`core-base`, `base/tenant/groups/`, free of Spring/servlet/OAuth2 types) turns a user's groups into `UserTenantAssignments`: groups of this deployment's application (`DIRIGIBLE_APP_ID`) become that tenant's roles, groups of other applications are ignored, and non-tenant-bearing groups (plain `DEVELOPER`, `OPERATOR`) stay global roles. The role part may contain dots; tenant and application ids may not. The groups claim is `DIRIGIBLE_TENANT_GROUPS_CLAIM` (`cognito:groups` by default, `groups` on Keycloak realms) — **set it explicitly on a Keycloak realm**: it is the one place both the login mapping and the selection read, so a wrong claim silently means "no tenants".
+
+## Tenant selection (`security-oauth2`, both OIDC profiles)
+
+What writes the session attribute — the identity-provider half of `TOKEN_GROUPS`. It lives in `security-oauth2` (`.../oauth2/tenant/`) rather than in a profile module, because Cognito and Keycloak need the same thing and their configurations differ only in the groups claim. Everything here is gated on the strategy, not on a Spring profile, so it is inert in `SUBDOMAIN` mode.
+
+- **`TenantAwareAuthoritiesMapper`** behind each profile's `userAuthoritiesMapper()`: in `SUBDOMAIN` mode every group of the provider's own claim becomes an authority (byte-identical to what the two profiles did inline before); in `TOKEN_GROUPS` mode only `globalRoles()`, since which tenant's roles apply is unknown at login.
+- **`TenantSelectionManager`**: `selectTenant` validates the tenant against the user's **own groups** (403 if not a member) and requires it `PROVISIONED` here (409), writes the session attribute and rebuilds the `OAuth2AuthenticationToken` with `globalRoles ∪ rolesFor(tenant)`, saved through the `SecurityContextRepository` — the `OAuth2SessionRevalidationFilter.refreshAuthentication` sequence, without rotating the session id. `ensureConsistent` re-applies them when they drift and **drops a selection whose group was revoked**.
+- **`TenantSelectionEndpoint`** at `services/security/tenant-selection`: `GET` lists `{selectedTenantId, tenants:[{id,name,provisionedHere}]}`, `POST {tenantId}` enters one and doubles as the switch. No `@RolesAllowed` on purpose — a user who has not picked yet has only global roles, and a single-tenant user none at all. JSON-only body is the CSRF defence (the chains disable CSRF tokens), as in `NativeLoginEndpoint`.
+- **`TenantSelectionFilter`**: one tenant → auto-select; several → `302 /tenant-selection.html` for a browser, `409 {"error":"TENANT_SELECTION_REQUIRED","tenants":[…]}` otherwise; none → pass for global-role holders, else 403. Non-`OAuth2AuthenticationToken` requests (M2M bearer, anonymous, basic) pass through.
+- **Registration** is `TenantSelectionSecurityConfigurator`, the repo's **first `CustomSecurityConfigurator`**. `HttpSecurityURIConfigurator.configure` applies those before its own matchers and every chain calls it, so one bean adds the filter `before AuthorizationFilter` (it must precede authorization, or a user without a tenant is 403'd before reaching the picker) and claims `/tenant-selection.html` as `authenticated()` — no per-profile wiring, no edit to the static URL matrix.
+- **The picker** is `security-oauth2/src/main/resources/static/tenant-selection.html` — Harmonia + Alpine, the load order of the Home landing page, inline script, `?switch=true` to change tenant. A classpath static page because the registry is itself tenant-scoped.
+
+⚠ In `TOKEN_GROUPS` mode the authorities of a session are **recomputed from the groups**, so a platform role such as `ADMINISTRATOR` must be granted as a *global group*; anything granted another way is dropped on the next request. Note also that a fresh selection applies from the **next** request: the tenant scope of the current one was opened before the selection was written, which is why the picker navigates away on success.
+
+`TenantResolutionConfigValidator` (`core-tenants`) refuses to start on an unusable combination: with `TOKEN_GROUPS` the app id must be set and dot-free, `DIRIGIBLE_MULTI_TENANT_MODE` must be true, the groups claim non-blank, and `DIRIGIBLE_MULTI_TENANT_MODE_COGNITO_SINGLE_USER_POOL` (the legacy `custom:tenant` model of `CognitoTenantFilter` / `KeycloakTenantFilter`, which resolve by subdomain and stand down under `TOKEN_GROUPS`) must be off. It validates **in its constructor** on purpose — a half-usable resolution setup must abort the context refresh rather than serve requests that silently land in the wrong tenant.
+
+Caches: `TenantExtractor.TENANT_CACHE` (by subdomain) and `TENANT_ID_CACHE` (provisioned tenants by id), both 10 min. Use `TenantExtractor.evictFromCaches(tenantId, subdomain)` after changing a tenant's registration or status; `TenantService.save/delete` already do.
+
+## Tenant-aware configuration (`commons-config` + `core-configurations`)
+
+Each tenant can override selected configuration values; overrides are resolved **per request**, scoped to the current tenant. Added on PR [#6205](https://github.com/eclipse-dirigible/dirigible/pull/6205).
+
+**Resolution precedence** (in `Configuration.get`): `RUNTIME (set() programmatic) → tenant thread map → ENVIRONMENT (env + sys props) → DEPLOYMENT (.properties) → MODULE`. The tenant map sits between the runtime variables and the environment, so a tenant override beats env/properties but a programmatic `Configuration.set` still wins.
+
+**Layering is load-bearing — do not break it.** `modules/commons/commons-config` sits at the bottom of the dependency graph and must stay dependency-free. It carries **only** the neutral mechanism: a `ThreadLocal<Map<String,String>>` in `Configuration` with `setThreadConfiguration` / `removeThreadConfiguration` / `getThreadConfiguration`, plus the `get()` precedence branch. It has **no** knowledge of tenants, DB, or where the values come from. Everything tenant/DB/policy-related lives one layer up in `components/core/core-configurations` (which depends on `data-sources`; `TenantContext` comes from `core-base`). Never add a tenant/DB dependency to `commons-config`.
+
+- **Store** (`tenant/TenantConfigurationStore`) — raw `SqlFactory` CRUD against `DataSourcesManager.getDefaultDataSource()`, which inside a tenant scope is auto-routed to that tenant's schema, so a distinct **`DIRIGIBLE_CONFIGURATIONS`** table (columns `CONFIGURATION_KEY` / `CONFIGURATION_VALUE`) lives per tenant schema; created create-if-absent on first use.
+- **Cache** (`tenant/TenantConfigurationCache`) — per-tenant map, loaded on first access, invalidated on write. Per-node only; a multi-node cluster would need an external invalidation signal (documented as out of scope).
+- **Key policy** (`tenant/TenantConfigurationKeyPolicy`) — an **explicit white-list of full keys (exact match, NO wildcards)**; default-deny for everything else, so a tenant can never shadow infrastructure keys. Allowed: the **branding** keys (`DIRIGIBLE_BRANDING_{NAME,SUBTITLE,BRAND,BRAND_URL,FAVICON,THEME,PREFIX,ANALYTICS}`) and `DIRIGIBLE_APPLICATION_LANGUAGES` (the per-tenant language set, default `en`). To widen, add concrete keys to `ALLOWED_KEYS` — do not reintroduce prefix/wildcard matching (that was explicitly rejected) and do not reintroduce a configurable `DIRIGIBLE_TENANT_CONFIGURATION_ALLOWED_KEYS` (removed). A non-allow-listed key can still be *stored* but is never injected.
+- **Request wiring** (`tenant/TenantConfigurationInitFilter`, `@Order(LOWEST_PRECEDENCE)`) — runs downstream of the Spring Security filter chain, i.e. **inside** the tenant execution scope established by `core-tenants`' `TenantContextInitFilter`; it loads the allow-listed entries into the thread map for the request and clears them in `finally`. **Do not move this into `TenantContextInitFilter`** — that would force `core-tenants` to depend on `core-configurations` (cycle). Keep it in `core-configurations`.
+- **REST** (`endpoint/TenantConfigurationsEndpoint`, `ADMINISTRATOR`/`OPERATOR`) at `services/core/configurations/tenant`: `GET` (stored entries), `GET /predefined` (every allowed key with the tenant's value or `null`), `PUT` `{key,value}`, `DELETE ?key=`.
+- **UI**: a built-in **Tenant Configuration** entry in the Harmonia **application shell** Settings (`components/resources/resources-application` — `views/_settings.html` + `js/appShell.js`), rendered locally like Region & Language: lists the predefined branding props with editable values (empty → platform default), Save/Reload, 403 → permission notice. A generic AngularJS CRUD view also exists in `components/ui/view-configurations` (`tenant-configurations.html`) for arbitrary keys.
+
+**Making a new property tenant-overridable (the whole recipe):**
+
+1. **Add the exact key** to `ALLOWED_KEYS` in `components/core/core-configurations/.../tenant/TenantConfigurationKeyPolicy.java` — a full key string, e.g. `"DIRIGIBLE_THEME_DEFAULT"`. No prefixes, no wildcards. This single edit is all that is functionally required: the key becomes injectable, is returned by `GET /services/core/configurations/tenant/predefined`, and **appears automatically** in the Harmonia Settings "Tenant Configuration" page (the page is data-driven from `/predefined`) and in the REST/AngularJS management surfaces.
+2. **Read it at request time.** The override only takes effect for code that calls `Configuration.get("<KEY>")` (or `DirigibleConfig.<X>.getStringValue()`) **during a request, inside the tenant scope**. A value read once at boot or cached in a bean/`static` field will not reflect per-tenant overrides — read it lazily per use. (Branding already works because the branding services read it live.)
+3. **Label (optional).** The Settings page derives a display label in `appShell.js` `tenantConfigLabel()`, which strips the `DIRIGIBLE_BRANDING_` prefix. For a non-branding namespace, extend that helper so the label reads nicely; otherwise it falls back to a de-prefixed, title-cased form of the key.
+4. **Tests.** Add the key to `TenantConfigurationKeyPolicyTest` (allowed set) and, if you want end-to-end coverage, mirror `TenantConfigurationIT` (set → resolve with precedence → clear).
+
+Do **not** widen by reintroducing wildcards or a config-driven allow-list — the explicit in-code white-list is deliberate (a tenant must never be able to shadow infrastructure keys).
+
+**SqlFactory quoting gotchas (bit this feature twice):** the `create().table()` builder takes **pre-quoted** identifiers (the `TableCreateProcessor` pattern), while `select/insert/update/delete` and the `where(...)` condition **auto-quote** — pass **unquoted** names there. A VARCHAR length arg must include its own parens: `column(..., "(255)")`, not `"255"` (renders `VARCHAR (255)`).
+
diff --git a/.claude/settings.json b/.claude/settings.json
index b1fbef4453a..0ee161a12ec 100644
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -5,7 +5,13 @@
       "Bash(git status *)",
       "Bash(git diff *)",
       "Bash(mvn formatter:format *)",
-      "Bash(mvn -P release *)"
+      "Bash(mvn -P release *)",
+      "Bash(git fetch)",
+      "Bash(git fetch *)",
+      "Bash(gh search *)",
+      "Bash(mvn formatter:validate *)",
+      "Bash(mvn -T 1C formatter:validate)",
+      "Bash(mvn -T 1C formatter:validate *)"
     ]
   }
 }
diff --git a/.gitignore b/.gitignore
index 79419637e32..91ab9054fda 100644
--- a/.gitignore
+++ b/.gitignore
@@ -38,8 +38,9 @@ package-lock.json
 **/version.txt
 # Ignore local Claude Code state (settings.local.json, run/, worktrees/) but
 # keep the shared dev-loop slash commands, their cross-platform driver script,
-# and the team-wide settings.json.
+# the team-wide settings.json, and the CLAUDE.md topic files it imports.
 .claude/*
 !.claude/commands/
+!.claude/docs/
 !.claude/scripts/
 !.claude/settings.json
diff --git a/CLAUDE.md b/CLAUDE.md
index 291a34a11c1..fba8b6cbe1f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4,542 +4,23 @@ Provides behavioral guidelines to reduce common LLM coding mistakes and guidance
 
 **Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
 
-## 1. Think Before Coding
-
-**Don't assume. Don't hide confusion. Surface tradeoffs.**
-
-Before implementing:
-- State your assumptions explicitly. If uncertain, ask.
-- If multiple interpretations exist, present them - don't pick silently.
-- If a simpler approach exists, say so. Push back when warranted.
-- If something is unclear, stop. Name what's confusing. Ask.
-
-## 2. Simplicity First
-
-**Minimum code that solves the problem. Nothing speculative.**
-
-- No features beyond what was asked.
-- No abstractions for single-use code.
-- No "flexibility" or "configurability" that wasn't requested.
-- No error handling for impossible scenarios.
-- If you write 200 lines and it could be 50, rewrite it.
-
-Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
-
-## 3. Surgical Changes
-
-**Touch only what you must. Clean up only your own mess.**
-
-When editing existing code:
-- Don't "improve" adjacent code, comments, or formatting.
-- Don't refactor things that aren't broken.
-- Match existing style, even if you'd do it differently.
-- If you notice unrelated dead code, mention it - don't delete it.
-
-When your changes create orphans:
-- Remove imports/variables/functions that YOUR changes made unused.
-- Don't remove pre-existing dead code unless asked.
-
-The test: Every changed line should trace directly to the user's request.
-
-## 4. Goal-Driven Execution
-
-**Define success criteria. Loop until verified.**
-
-Transform tasks into verifiable goals:
-- "Add validation" → "Write tests for invalid inputs, then make them pass"
-- "Fix the bug" → "Write a test that reproduces it, then make it pass"
-- "Refactor X" → "Ensure tests pass before and after"
-
-For multi-step tasks, state a brief plan:
-```
-1. [Step] → verify: [check]
-2. [Step] → verify: [check]
-3. [Step] → verify: [check]
-```
-
-Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
-
----
-
-**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.
-
-## Project
-
-Eclipse Dirigible — a high-productivity application platform (hpaPaaS). The runtime is a single Spring Boot fat jar that bundles an in-browser IDE plus execution engines (GraalJS, Flowable BPM, Camel, Quartz, Lucene, CMS, OData, etc.). It supports "In-System Programming": users develop and modify the running system through the browser. The shipped artifact is `build/application/target/dirigible-application-*-executable.jar`; the entry point is `org.eclipse.dirigible.DirigibleApplication` (`build/application/src/main/java/org/eclipse/dirigible/DirigibleApplication.java`).
-
-## Prerequisites
-
-- Java JDK 21 (project compiles to Java 21; CI builds/tests run on Corretto 24, bytecode target stays 21)
-- Maven 3.8.x
-- Node.js 22.x with global installs of `typescript` and `esbuild` (frontend WebJars are transpiled/bundled at build time)
-- `ttyd` (only required at runtime for the in-IDE terminal on port 9000, and for integration tests)
-
-## Build
-
-The whole project is a multi-module Maven build at the root. The Maven coordinates are `org.eclipse.dirigible:dirigible-parent` (currently `14.0.0-SNAPSHOT`).
-
-| Goal                                | Command                                                            |
-| ----------------------------------- | ------------------------------------------------------------------ |
-| Full build with all unit tests      | `mvn clean install`                                                |
-| Fast build (no tests/javadoc/license/format) | `mvn -T 1C clean install -P quick-build`                  |
-| Unit tests only (no ITs)            | `mvn clean install -P unit-tests`                                  |
-| Run unit + integration tests        | `mvn clean install -P tests`                                       |
-| Integration tests only              | `mvn clean install -P integration-tests -D selenide.headless=true` |
-| A specific IT (comma-separated)     | `mvn clean install -P integration-tests -Dit.test="CsvimIT,CreateNewProjectIT" -D selenide.headless=true` |
-| A specific unit test (single module) | `mvn -pl <module-path> -am test -Dtest=ClassName#method`          |
-| Format Java code                    | `mvn formatter:format` (or `-P format`)                            |
-| Validate formatting (what CI runs)  | `mvn -T 1C formatter:validate`                                     |
-| Static analysis                     | `mvn clean install -P spotbugs`                                    |
-| Coverage report (JaCoCo)            | `mvn clean -B package -P coverage`                                 |
-| Update license headers              | `mvn license:format -P license -DskipExistingHeaders=false`        |
-
-The Java formatter profile is `dirigible-formatter.xml` at the repo root — CI fails the build on formatter violations, so run `mvn formatter:format` (or rely on the IDE save action configured per `CONTRIBUTING.md`) before pushing.
-
-Tests follow Maven's surefire/failsafe split: `*Test` runs under surefire (unit), `*IT` runs under failsafe (integration). Integration tests are Selenide-based UI tests living in `tests/tests-integrations/src/main/java/.../tests/`. The build profile `integration-tests` disables surefire and only runs failsafe.
-
-## Run
-
-After a build:
-
-```
-java -jar build/application/target/dirigible-application-*-executable.jar
-```
-
-UI at `http://localhost:8080`, default credentials `admin`/`admin`. Useful URLs on the same port:
-
-- `/` — redirects to the IDE entrypoint (default `services/web/shell-ide/`, configurable via `DIRIGIBLE_HOME_URL`)
-- `/swagger-ui/index.html`, `/api-docs` — OpenAPI / Swagger UI for built-in REST endpoints
-- `/spring-admin/` — Spring Boot Admin (server profile enabled in this app)
-- `/actuator/health/readiness`, `/actuator/health/liveness` — health probes (also what the CI DAST job polls)
-- `/services/...` — secured Spring-side endpoints (see `BaseEndpoint.PREFIX_ENDPOINT_*`)
-- `/public/...` — unauthenticated counterpart
-- `/services/js/<project>/<file>.{js,mjs,ts}` — execute a JS/TS file from the user repository (the same path under `/public/js/` is the unauthenticated variant)
-- `/odata/v2/...` — OData services (CXF base path)
-- `/websockets/...` — WebSocket endpoints
-
-Default DB is **file-backed** H2 at `jdbc:h2:file:./target/dirigible/h2/DefaultDB;LOCK_TIMEOUT=10000` (see `components/data/data-sources/src/main/resources/META-INF/dirigible/datasources/DefaultDB.datasource` — this is also why `mvn clean` is required when switching DBs, the old H2 files survive otherwise). Switch by exporting `DIRIGIBLE_DATASOURCE_DEFAULT_DRIVER/URL/USERNAME/PASSWORD`. Server port is overridable via `DIRIGIBLE_SERVER_PORT` (default 8080). The in-IDE terminal launches `ttyd` on 9000. The Dockerfile additionally exposes 8081 as the Graalium debug port (env var `DIRIGIBLE_JAVASCRIPT_GRAALVM_DEBUGGER_PORT`; debugging is on by default via `DIRIGIBLE_GRAALIUM_ENABLE_DEBUG=true`).
-
-The on-disk Dirigible repository ("registry") defaults to `./target/` relative to the working directory (`DIRIGIBLE_REPOSITORY_LOCAL_ROOT_FOLDER`). Inside it the canonical layout is `/registry/public/<project>/...` for published artefacts and `/users/<user>/workspace/<project>/...` for in-IDE workspaces (see `IRepositoryStructure`). Multi-tenancy is on by default (`DIRIGIBLE_MULTI_TENANT_MODE=true`).
-
-For remote debugging:
-
-```
-java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8000 -jar build/application/target/dirigible-application-*-executable.jar
-```
-
-## Local dev-loop automation (`.claude/` commands + script)
-
-The repo ships Claude Code slash commands (`/dirigible-start`, `/dirigible-stop`, `/dirigible-logs`, `/dirigible-test`, `/dirigible-pr` in `.claude/commands/`) wrapping one cross-platform Node.js driver (`.claude/scripts/dirigible.mjs`) for the local build/run/log/test/PR loop. Prefer these over hand-running `mvn`/`java`. **Maintainer reference (read before changing the commands or driver): [`.claude/scripts/README.md`](.claude/scripts/README.md)** — driver subcommands, cross-platform mechanics, the background-task log-tail rationale, and the team-wide permission whitelist in `.claude/settings.json`. The user-facing guide is the "Claude Code Commands" section of the root `README.md`.
-
-## Repository layout
-
-The Maven hierarchy (from root `pom.xml`) is: `modules`, `components`, `build`, `dependencies`, `tests`, `cli`. Each is a Maven aggregator.
-
-- **`modules/`** — low-level platform building blocks consumed by everything else: `commons`, `database`, `engines` (script engine abstractions), `odata`, `parsers`, `repository`. These are pure libraries with no Spring wiring.
-- **`components/`** — the Spring application surface, split by concern. The `build/application` module wires all of these together via Spring Boot auto-configuration — there is no manual "list of features"; capability comes from whichever components/* JARs are on the classpath.
-  - `components/core/` — base Spring infrastructure: `core-base`, `core-configurations`, `core-database`, `core-extensions`, `core-initializers`, `core-registry`, `core-repository`, `core-spring`, `core-tenants`, `core-tracing`, `core-version`, `core-healthcheck`, `core-project`.
-  - `components/engine/` — runtime execution engines: `engine-java` (client `.java` runtime — synchronizer + compiler + SPI; see "Client Java code" below), `engine-javascript` (GraalVM polyglot), `engine-typescript`, `engine-bpm-flowable` (workflows), `engine-camel` (integration routes), `engine-jobs` (Quartz), `engine-listeners` (message listeners), `engine-cms-*` (internal / S3 / SharePoint), `engine-odata`, `engine-openapi`, `engine-web`, `engine-websockets`, `engine-template-*`, `engine-open-telemetry`, etc. Each engine registers itself as a Spring component and contributes routes/processors/scheduled jobs to the running app.
-  - `components/api/` — Java implementations of JS/TS APIs that user code in the IDE can `import` (e.g. `api-database`, `api-http`, `api-mail`, `api-git`, `api-bpm`, `api-cms`, `api-s3`, `api-kafka`, `api-rabbitmq`, `api-mongodb`, `api-pdf`, ...). These are bridged into GraalJS by `engine-javascript`.
-  - `components/data/` — data-layer tooling: `data-sources`, `data-structures` (HDB-style table definitions), `data-management`, `data-import`/`-export`, `data-csvim` (CSV import model), `data-store` (TS `@Entity` decorators → Hibernate via HBM XML), `data-store-java` (Java `@Entity` annotations → same Hibernate machinery; consumes `engine-java`'s SPI), `data-transfer`, `data-processes`.
-  - `components/ide/` — the browser IDE: a large set of `ide-ui-*` WebJar modules (Monaco, perspectives for git/bpm/database/jobs/etc.) plus backend services `ide-git`, `ide-terminal`, `ide-workspace`, `ide-console`. Frontend assets are bundled with `esbuild`/`tsc` during the Maven build, hence the Node toolchain prerequisite.
-  - `components/platform/`, `components/platform-ide/`, `components/security/`, `components/template/`, `components/ui/`, `components/resources/` — perspective/branding/security plumbing and shared UI assets.
-  - `components/group/` — _Maven aggregators only_ (`group-api`, `group-engines`, `group-ide`, ...). When you add a new component module, register it in the matching `group-*/pom.xml` so the assembly picks it up.
-- **`build/application/`** — the only thing that turns the above into a runnable jar. `DirigibleApplication.java` is intentionally small (just `@SpringBootApplication` + `@EnableAdminServer` + Camel OpenTelemetry). `Dockerfile` lives here too.
-- **`tests/tests-framework/`** — shared Selenide/Spring test base classes used by ITs.
-- **`tests/tests-integrations/`** — `*IT.java` UI integration tests plus project fixtures under `src/main/resources/<TestName>/`. Each IT fixture directory is a Dirigible project that gets imported and exercised through the running app.
-- **`cli/`** — standalone helper that starts the Dirigible jar against a given user project path; produces `cli/target/dirigible-cli-*-executable.jar`. See `cli/README.md`.
-- **`maven-plugins/flowable-bpmn-docs-maven-plugin/`** — custom Maven plugin generating BPMN docs.
-- **`dependencies/`** — BOM-style module aggregating third-party version pins (the actual `<properties>` for versions still live in the root `pom.xml`).
-- **`open-telemetry/`**, **`samples/`**, **`misc/`**, **`npm/`** — auxiliary content, not part of the Maven reactor in the root build (verify in the relevant `pom.xml` before assuming).
-
-## How a feature reaches the running system (the synchronizer model)
-
-This is the single most important architectural pattern to understand before changing engines or adding artefact types. Dirigible does not "deploy" projects — instead, files in the repository (`/registry/public/...`) are continuously reconciled into runtime state by **synchronizers**.
-
-Each artefact type has three collaborating pieces:
-
-1. An **Artefact** JPA entity (`extends Artefact` from `components/core/core-base`) — the persisted projection of a file.
-2. A **Synchronizer** (`extends BaseSynchronizer<A, ID>` or `MultitenantBaseSynchronizer`) — registered as a Spring bean, scans the repository for a specific file extension/pattern, parses it, upserts the artefact, and reacts to lifecycle phases (`CREATE`, `UPDATE`, `DELETE`, `START`, `STOP`). Ordering across synchronizer types is fixed in `SynchronizersOrder`.
-3. An optional **engine/service/endpoint** that consumes the live artefact (e.g. Quartz scheduler for jobs, Flowable for `.bpmn`, Camel for routes, Spring MVC endpoints for `expose` declarations).
-
-Existing synchronizer implementations (grep `extends BaseSynchronizer` / `extends MultitenantBaseSynchronizer`) give a complete inventory of supported artefact types: `Job`, `Bpmn`, `Camel`, `Listener`, `Csvim`, `DataSource`, `Table`, `View`, `Access` (security), `Expose` (URL routing), `ExtensionPoint` / `Extension`, `Markdown`, `Proxy`, `PrintTemplate` (`.print` → CMS seeding), etc. Adding a new artefact type means producing a new synchronizer + entity + (usually) a service, then registering it in the relevant `group-*` aggregator.
-
-JS/TS user code is **not** synchronized — it is loaded on demand by `engine-javascript` (`JavascriptEndpoint` at `/services/js/...`, `/public/js/...`) via `DirigibleJavascriptCodeRunner` backed by Graalium/GraalVM polyglot. The `api-*` Java modules under `components/api/` register the JS-callable APIs (`@dirigible/db`, `@dirigible/http`, etc.) into the GraalJS context — pre-built TS/JS bundles for those APIs live in `components/api/api-modules-javascript/src/main/resources/META-INF/dirigible/modules/`.
-
-## Client Java code (`engine-java` + `data-store-java`)
-
-Client `.java` under `/registry/public/<project>/...` is synchronized by `JavaSynchronizer`, compiled in-process (one `javac` batch + one fresh `ClientClassLoader` per generation in `JavaLoader.rebuild()`), and run through a Spring-Boot-style **bean container** (PR [#6051](https://github.com/eclipse-dirigible/dirigible/pull/6051)):
-
-- `@Component` beans with **constructor / field / collection** injection; `@Repository`, `@Controller`, `@Websocket` are meta-`@Component`. Reach platform services via the client-facing `Beans` facade (not the platform-internal `BeanProvider`).
-- **Two never-mixed handler styles** for jobs/listeners/websockets: a self-describing interface (`JobHandler.cron()`, `MessageHandler.destination()`, `WebsocketHandler.endpoint()`) **or** a method-level annotation (`@Scheduled`/`@Listener` on a `@Component` method; `@Websocket` class + `@OnX` methods). No reflective by-name fallback; the hybrid is rejected.
-- **Extension points are plain interfaces** + `@Component` contributions consumed via `List<…>` injection (or `Extensions.find`); there is no `@Extension`/`@ExtensionPoint`.
-- All client annotations/facades live in `org.eclipse.dirigible.sdk.*` (`api-modules-java`), not the old `engine.java.annotations.*`. Compile **and** bean-wiring errors surface in the IDE Problems view.
-- **Manage entities ONLY through their generated `<Entity>Repository` — never the generic `Store`/`Database` for entity CRUD.** The generated `@Repository extends JavaRepository<T>` is the sole sanctioned load/save/update/delete path; it carries validations, **event publishing** (create/`-updated`/`-deleted` topics that intent triggers/reactions/rollups/notifications consume — recorded in the tenant's `DIRIGIBLE_EVENT_OUTBOX` inside the write's own transaction, so the row and its event commit together and a broker outage neither loses the event nor fails the write; `EventOutboxRelayJob` drains what the in-process publish could not deliver), and — for `multilingual: true` entities — the **read-time translation overlay** (every find translates string properties from the sibling `<TABLE>_LANG` table for the caller's `Accept-Language`, via the SDK `org.eclipse.dirigible.sdk.db.Translator`). The name-keyed `org.eclipse.dirigible.sdk.db.Store` and raw `Database` SQL bypass all of that silently and must not touch a managed entity. (`updateWithoutEvent` is fine — a deliberate repository method that keeps validations/i18n and only omits the event, for workflow-driven system writes.) So a reusable delegate/service that must touch a *specific* entity lives **in that entity's project** (importing its repository); only entity-agnostic helpers belong in a shared project. See the engine-java guide.
-
-**Detailed guide:** [`components/engine/engine-java/CLAUDE.md`](components/engine/engine-java/CLAUDE.md). Read it before changing anything under `engine-java`, `data-store-java`, the `sdk.*` annotations, or the `*-java` templates — it covers the container, the consumers, the two handler styles + no-mixing rule, the `JavaHandler`-as-bean path, controller routing / OpenAPI / `@Roles`, `data-store-java` dynamic-map persistence, error surfacing, the **removed** internals (`RepositoryRegistry` / `RepositoryClassConsumer` / `DependencyResolver` / reflective fallback / `@Extension`), and the three-repo (platform + `dirigiblelabs/sample-java-*` + docs) sequencing.
-
-## Intent layer (`engine-intent` + `editor-intent`)
-
-A single `app.intent` YAML file at a project root is the source of truth one altitude above the model files. **The intent is an authoring artifact, not a runtime artifact** — like the `.edm` it has an editor and an explicit Generate, and (like the `.edm`) it has **no synchronizer**. Double-clicking any `*.intent` file opens the Intent Editor (`components/ui/editor-intent`): editable YAML left, live read-only diagram right (mxGraph ER + per-process flowcharts, the same engine the EDM/schema/mapping modelers use), validation inline; the Generate button runs six generators that write `.edm`/`.model`, `.bpmn`, `.form`, `.report`, `.roles` and `.csvim`/`.csv` **into the developer's workspace project at the project root** (the layout of real-world Dirigible application projects) — nothing touches the registry until normal publish, after which the per-artefact synchronizers bring the runtime live as for any project. Services: `POST /services/ide/intent/parse` and `POST /services/ide/intent/generate`. A third editor pane is a **Claude AI assistant** (`POST /services/ide/intent/agent`): it proposes the complete updated `app.intent` via the Anthropic API (key server-side in `DirigibleConfig.INTENT_AI_*`, never sent to the browser), the editor shows a Monaco diff, and Accept merges it into the buffer — the agent never writes disk or runs Generate. Developed on PR [#6017](https://github.com/eclipse-dirigible/dirigible/pull/6017). **A second assistant continues past the DSL's boundary into the Workbench** (issue [#6724](https://github.com/eclipse-dirigible/dirigible/issues/6724)): the Workbench's right-region **Assistant** view (`components/ui/view-assistant`, tracking the open editor over the layout hub) helps write the hand-written Java the model deliberately does not express (a `CalculatedField` action, a `JavaDelegate`) via `POST /services/ide/intent/assist`, proposing a complete `custom/*.java` that is **really compiled — batched with the project's other sources, as the runtime compiles it —** before the developer sees the diff, then written on an explicit Accept. It reasons about the editor's live buffer (`editor.content.request`, answered by `editor-monaco`), not the file on disk, and its conversation persists under the `workbench` surface. Both go through one shared `...intent.ai` layer (one API key, one HTTP client, one bounded repair loop); the intent agent still never emits Java and the Java assistant never touches `gen/`. **The hand-off between them is explicit**: the intent agent's proposal carries a structured `boundaries` list (issues [#6713](https://github.com/eclipse-dirigible/dirigible/issues/6713) / [#6721](https://github.com/eclipse-dirigible/dirigible/issues/6721)) — every requirement the DSL cannot express, why, and which extension point carries it — rendered as its own bubble in the Intent Editor and the Builder rather than buried in prose, and a named `calculatedAction*` gets a generate-once `custom/` stub so the boundary is a file to open. **The conversation itself IS persisted** — the one thing this module keeps in the database: a tenant-aware, append-only pair of system tables keyed by `(tenant, project, surface, path)`, read/written through `GET /services/ide/intent/conversations` + `POST .../conversations/messages` (issue [#6668](https://github.com/eclipse-dirigible/dirigible/issues/6668)), so opening an app on any machine restores the same dialogue and support can reconstruct which proposal produced which change. The intent *document* still has no table and no synchronizer — see the module guide's "Conversation store" section for the distinction and the `note`-vs-`assistant` role rule.
-
-**Detailed guide:** [`components/engine/engine-intent/CLAUDE.md`](components/engine/engine-intent/CLAUDE.md). Read it before changing anything under that module — it covers the editor-first architecture and altitude contract (model files only, never code), the YAML schema and its semantics (integer-only primary keys, `composition: true` to-one = DEPENDENT master-detail while `required` alone is just a NOT NULL FK, PascalCase property names with UPPER_SNAKE columns, decision `then`/`else`, intent-prefixed table names via `IntentNaming`), the `writeModelFile`-only write surface with the stale-output scrub, the wrong turns already made (wrong altitude, template-output paths, registry-relative vs repository-absolute paths, the `JsonHelper` Gson pitfall, **and the synchronizer-based first incarnation — do not reintroduce it**), and the follow-up list (chaining model-to-code via `.gen` descriptors, `/custom/` escape hatch). Process triggers (`trigger: { onCreate: <Entity> }`) are wired: the EDM adds a `ProcessId` field + its per-process `ProcessIds` stamps sibling + a `triggers` collection to the `.model`, and the `template-application-events-java` template generates a `gen/events/<module>/<Process>Trigger.java` listener (module-scoped package `gen.events.<module>` — two modules authoring same-named reactions no longer collide by FQN; generated beans/entities carry module-qualified names for the same reason) that starts the process on create. That persisted `ProcessId` is in turn **consumed by the generated entity-view UI**: the shared Harmonia runtime's `processTasks` store (`components/resources/application-core/.../application-core/shell/js/stores/processTasks.js`) surfaces the record's actionable BPM user tasks inline (correlating `entity.ProcessId === task.processInstanceId`), wired into every generated view gated on a `hasProcess` flag; the task form completes via the permission-checked `/services/inbox/tasks/{id}` and self-closes (#6074). `IntentEngineIT` is the HTTP-only end-to-end test (~1 minute, no sync cycles). The editor's diagram pane is **mxGraph** (replacing Mermaid, which had unfixable light/dark theming bugs) with a fixed brand-colour palette that reads on both themes — see the module guide's "Intent Editor diagram = mxGraph" section before touching `editor-intent/js/editor.js`.
-
-**Multi-model + layout additions (PRs [#6089](https://github.com/eclipse-dirigible/dirigible/pull/6089)-[#6092](https://github.com/eclipse-dirigible/dirigible/pull/6092)):** the DSL now supports building an app from **several intent models that reference each other cross-model** - a top-level `uses:` block names other models, and a relation gains an optional `model:` alias; a cross-model `manyToOne`/`oneToOne` is emitted as a read-only **PROJECTION** entity + integer FK + dropdown (the codbex cross-project pattern - no local table/DAO/controller for the target), resolved against the owner's already-generated `.model` (leaf-first generation; convention fallback otherwise). **n:m** is always an **intermediate (link) entity** (composition to one side + `manyToOne` to the other, which may be cross-model): `kind: manyToMany` **materializes** that entity at parse time (`ManyToManyExpander` — `<Declaring><Target>`, or the relation's `through: <Name>`, with a generated key + both FKs; the authored relation becomes the navigation-only `oneToMany` to it, so no generator ever sees a `manyToMany`), while a link carrying **bridge fields** like `amount` is authored explicitly and drops the `manyToMany`. The VALUE-set counterpart is **`kind: subset`** (#6878): a record holding a subset of a small lookup's rows with no data on the pairing lowers to ONE plain VARCHAR column (`"1,3"` — keys comma-separated, ascending, de-duplicated; empty = null) rendered as a Harmonia multi-select (`widgetType: MULTISELECT` + `widgetOptionsEntityName` — never `relationshipEntityName`, whose presence alone makes the schema template emit an FK); the moment the pairing needs bridge data, reverse navigation or row consumers (forEach/related/rollups/reports), it has outgrown a value — see the engine-intent guide's subset bullet. New field attributes: `unique`, `precision`/`scale`, `calculatedOnCreate`/`calculatedOnUpdate` (a neutral arithmetic expression for numeric totals, else emitted verbatim into the runtime), `calculatedActionOnCreate`/`calculatedActionOnUpdate` (server-side call-out to a hand-written `@Component implements org.eclipse.dirigible.sdk.db.CalculatedField<E,T>`, invoked as `Beans.get(<class>.class).calculate(entity)`, taking precedence over the expression — for logic too custom to model, e.g. number generation); field `readOnly: true` (not editable; rendered in the Harmonia form's read-only details block — Label:Value above the buttons — via `isReadOnlyProperty`; `ProcessId`/audit columns/`uuid` are auto-flagged read-only, `status`-style fields opt in); field `major: false` (kept off the entity **list** table — the model's `widgetIsMajor="false"` — still shown in forms + the record details pane; defaults true); entity `imports:` (Java `import` lines injected into the generated repository so a calculated action can be referenced by simple name — Base64-encoded into the `.model`'s `importsCode`, which the Java DAO template emits; the editor's entity-level Imports tab is the model-editor equivalent); entity `audit: true` (the four standard audit columns); entity `group:` (the perspective's nav-group id in the shared application shell). **Depends-On** is exposed as `dependsOn: { relation, valueFrom?, filterBy? }` on a to-one relation (cascading/narrowed dropdown) or a field (auto-populated value) — emitted as the EDM `widgetDependsOn*` attributes (the AngularJS stacks consume them as-is; the Harmonia runtime — form/document watchers + the metadata-driven item-dialog cascade — was added alongside); defaults are the respective primary keys, names are the target's authored property names, cross-model triggers/targets supported. **Multi-language data** (the TS-era `multilingual` port): entity `multilingual: true` → the schema layer generates a sibling `<TABLE>_LANG` table (`GUID, Id, <PascalCase translatable columns>, Language` — the codbex-uoms-data convention) and the generated Java repository overlays translated values on every read for the request's `Accept-Language` (SDK `Translator`, name-based merge); the supported language set is a PLATFORM concern (`DIRIGIBLE_APPLICATION_LANGUAGES`, default `en`, tenant-overridable via the tenant configuration) — the Harmonia **Region & Language** Settings entry always offers that set (an Alpine `locale` store, localStorage `codbex.harmonia.language`, sent as `Accept-Language` by the shared fetch client — one flag drives UI, data, and the Print default), while the top-level `languages: [en, bg]` only declares which languages the module PROVIDES translations for; the application shell warns about modules missing a platform language, and untranslated content falls back to the default; translations are authored as seeds with `language: bg`, and large data sets reference an authored CSV via seed `file: data/x.csv` (subfolder mandatory — root `.csv` is scrub-owned) instead of inline rows. **Related registers** (`related: [{ entity, model?, via?, label?, show? }]` on an entity, #6673) are the reverse of an incoming to-one association: the REFERENCED entity's page lists the records pointing at it (a project-month's timesheet lines, a customer's invoices, an account's journal entries), read-only, each row opening the source's own record page — declared on the referenced side because a referencing model is generated later and knows nothing about this one, filtered through the source controller's generic `POST /search` (the `?<fk>=<id>` parameter exists only on a details layout), and refused for a composition child, which is already the editable detail/items collection. **A schedule's `where` value may be a moment relative to now** (`"CURRENT_TIMESTAMP-PT30M"` / `"CURRENT_DATE+P7D"`, #6764): `<token><+|-><ISO-8601 duration>` resolved against the clock of the run that fires, which is what makes a staleness sweep expressible at all — `ScheduleSupport.Moment` is shared by the parser and the generator, a date-only amount emits a `Period` and a time-bearing one a `Duration` (`LocalDate.minus(Duration)` throws, `Duration.parse("P1M")` does not parse), and the token's shape must match the queried field's — enforced for a bare token too, so a `CURRENT_TIMESTAMP` handed to a DATE column stops being a silent never-match. A master owning an `*Item` composition child renders as the **document (header-items) layout** (`MANAGE_DOCUMENT` + `documentItemsEntity`, `uiDocumentModels`), with `aggregate: true` fields shown in the totals footer. `IntentNaming.upperSnake` collapses kebab/space/`.`/`/` separators so a hyphenated model name yields a valid SQL identifier (`sales-invoices` -> `SALES_INVOICES`). Worked example: `dirigiblelabs/sample-intent-multi-model` (six interdependent projects + a navigation-groups project).
-
-**First-class document numbering (`number:` + the `.numbers` artefact, `engine-numbering`):** a string field may declare `number: { series: Sales Invoice, per: Company, stampOn: create|issue }` — the intent references a **series by name only**; the number's shape (literal prefix + sequence zero-padded to a total width, no token grammar) lives OUTSIDE the model: declared per module in an authored **`.numbers`** artefact (`{"series": [{"name": "Sales Invoice", "prefix": "SI", "size": 10}]}`, a requirement declaration like `.roles`) and configured per tenant in the application shell's Document Numbering settings (`/services/core/numbering`). One per-tenant table `DIRIGIBLE_DOCUMENT_NUMBERS` holds shape AND counter, one row per (series, partition); the synchronizer only INSERTs missing rows, Settings writes prefix/size/next, the allocator (`sdk.numbering.DocumentNumbers.next`) increments the counter — sequences are continuous, never auto-reset, and allocating an undeclared series fails loudly. `per:` partitions a series by a to-one relation's value (per company — two legal entities never share a counter); the declaration may name the **partition source** (`"partitions": {"table", "key", "label"}` — authored physical coordinates) so Settings labels partition rows by the entity's display name and lists a VIRTUAL row per value before its first allocation (saving provisions it — seed a company's starting number before its first document). A differing cross-module re-declaration fails that artefact naming both modules; the removed `format`/`scope`/`resetOn` keys are rejected at parse. Details in the engine-intent guide's numbering bullet.
-
-**Effective-dated register lookup (`resolves:`, [#6712](https://github.com/eclipse-dirigible/dirigible/issues/6712)):** a to-one filled from the register row whose validity period covers a date the record carries — the driver from a vehicle-assignment register on the violation date, the price from the list in force on the order date, the approver from the org assignment on the request date. `resolves: - { name, event: { onCreate|onUpdate: <Record>, when? }, set: <to-one>, from: <Register>, match: { <registerProperty>: <recordProperty> }, between: { start?, end?, value }, outcome?: <string field>, found?/notFound?/ambiguous?: { setStatus } }` → a `resolves` glue descriptor → a generated `@Component MessageHandler` on the record's event topic. **All three outcomes are first-class:** exactly one covering row fills the relation, while zero and more-than-one both leave it unset — an automation that silently picks one of two candidates is worse than none, so an ambiguous register goes back to a human. Each outcome may route by `setStatus` (id or seeded name) and the attempt is observable: `outcome:` stamps `found`/`notFound`/`ambiguous` into a string field a list filter or a process `decision` can read. The copied value is derived, not authored — the register must carry exactly ONE to-one to the same target as `set:`, and zero or two is a validation error; a record that already carries the relation is skipped (a manual correction is never overwritten); the relation + outcome + status go out in ONE targeted `updateProperties`; a bound may be omitted on either side (open-ended), the end is inclusive, and a date-only bound covers its whole day. v1 is same-model and `onCreate`/`onUpdate` only. Details in the engine-intent guide's `resolves:` bullet.
-
-**The declarative state machine (`lifecycle:`, [#6714](https://github.com/eclipse-dirigible/dirigible/issues/6714)):** an entity may declare the WHOLE set of legal status edges over its `function: EntityStatus` nomenclature — `lifecycle: { edges: [{ from: DRAFT, to: [ISSUED, CANCELLED] }, ...] }`, either side a seeded name or an id — and every status write is validated against it. Until then the status machinery was point constructs (`init:`, a `transitions:` button's own guard, a workflow `setRelationField`, a check's rejection) with nothing stating which moves were legal at all, so any writer that was not a transition button could move a document from any status to any other. Enforcement is in the generated **repository** — the one choke point every writer passes through (`update`, `updateWithoutEvent`, and `updateProperties`, which the transition controller's `updateProperty` and the workflow setters route through) — rejecting an unmodeled move with 400 and a message naming both statuses; with `init:` declared, a record cannot be CREATED mid-lifecycle either. At parse time the graph is what the other status sites are held to: a `transitions:` entry's `from`→`setStatus` pair must be a declared edge (a button is presentation over the graph), and a status written by a workflow step or forced by a check must be one some edge reaches — so a reject path transiting through an approved status fails when the intent is read. There is no `on:` key (the graph is always over the EntityStatus relation, and YAML reads a bare `on` as `true`, so it is refused rather than silently dropped), and a cross-model nomenclature is declared where it is seeded. Details in the engine-intent guide's state-machine bullet.
-
-**Naming a rendered document (`fileName:`, [#6899](https://github.com/eclipse-dirigible/dirigible/issues/6899)):** the two server-side PDF renders — the snapshot copy a document mints on issue and the `attach: print` PDF a `notify` block sends — accept a **`fileName:`** pattern on the `function: Snapshot` child / inside the notify block: literals plus `{token}` interpolations, no expression language. `{field}` and one-hop `{relation.field}` use the same path vocabulary and **authored names** a notify subject does, `{field:pattern}` formats a `date`/`timestamp` through a `DateTimeFormatter` pattern, `{A|B}` renders the first non-blank operand, `{Version}` (snapshot only) places the copy's version and a pattern without it gets `_v<n>` appended. Interpolated **values** are sanitized at run time by `sdk.print.FileNames` (trim, whitespace → one `_`, path/control characters stripped, non-ASCII deliberately kept); the literal separators are the author's. A pattern's relation loads are **merged into the notify block's own**, deduped by local, so a name may read a relation the message never mentions — but `attach: recordPrint` renders the anchor once, before the per-row loop, so only fields of the anchor are readable there. Absent a pattern, the snapshot default **changes** from the old primary-key form (`Order 42 v1.pdf`) to the same number-or-id expression the mail already used, plus the version — the deliberate fix for the two names disagreeing. An unresolvable path, an unbalanced brace, a format on a non-date field or a pattern that interpolates nothing are validation errors. Details in the engine-intent guide's fileName bullet.
-
-**User-set report parameters (`reports[].parameters`, [#6357](https://github.com/eclipse-dirigible/dirigible/issues/6357)):** a report reads for a period, a threshold or a name the user chooses — `- { name: fromDate, target: issuedOn, op: ge }` renders an input above the report and binds it into the query's `WHERE`, where `target:` is a field of the source or a one-hop `relation.field` (so a parameter may filter by a column the report does not display), `op:` is `ge`/`le`/`eq`/`like` and `initial:` is the value bound when the input is empty. This is the **authoring** half only: `kind: balance` already emitted `.report` `parameters`, and the generated repository, the controller's `@QueryParam` list and the Harmonia page's parameter strip were generic over them all along. Each term is a plain binary comparison against a named marker — a structured `conditions` row, so a parameter never parks the report in the editor's free-style mode — which is why the parameter is bound on EVERY call and the neutral case rides `initial` rather than a nullable predicate: `initial` is required unless the comparison has a neutral "any value" default (a date bound, a `like` search). A **nullable** target is read through its empty value, because a plain comparison drops every row holding no value in that column the moment a parameter is declared, before the user touches anything. Details in the engine-intent guide's parameters bullet.
-
-**Mailing a REPORT (`attach: { report, bind }`, [#6931](https://github.com/eclipse-dirigible/dirigible/issues/6931)):** the report-side sibling of `attach: print`. Where a dunning reminder carries the one invoice it is about, a **customer statement** carries a period of rows - a report, not a document - so a notify block may now name a declared report and bind its `parameters:` from the recipient row: `attach: { report: CustomerStatement, bind: { customer: name, fromDate: periodStart, toDate: periodEnd } }`. `bind:` values are a field or a one-hop `relation.field` of the record the message is about (the ROW inside a `forEach`), resolved through the same resolver a `{placeholder}` uses so the relation loads are shared locals. **Every parameter that declares an `initial` must be bound** - a parameter is bound on every call (#6911), so an unbound one rides its `initial`: one FIXED slice, identical for every recipient, which is the "whole ledger to one customer" failure mode (the mail goes out, the attachment IS a report, and nothing about it says whose). A parameter with no `initial` has a neutral any-value default (a date window bound, a `like` search), so omitting it means the whole range; a balance report's own `fromDate`/`toDate` are bindable and optional for the same reason. The render goes through a **`.print` template of the report's own** - seeded once at `doc/Templates/<Report>/Print/en/standard.print` for reports something actually mails, and developer-owned afterwards like the document scaffold. It is built from the columns the `.report` pass just resolved, so every `{{alias}}` is a key the query really SELECTs, and the **bound parameters are its header**: a table of rows never states which slice it is. Since `attach` now takes a map as well as a scalar, `NotificationIntent.attach` is typed `Object` and `getAttach()` reports only the KIND (`print` / `recordPrint` / `report`). Details in the engine-intent guide's *mail a REPORT* section.
-
-**Lifecycle-aware aggregates (`stage:` + `scope:` + symbolic statuses, [#6645](https://github.com/eclipse-dirigible/dirigible/issues/6645)):** a status seed row classifies what it MEANS to the lifecycle — `stage: draft|live|cancelled|void`, metadata never emitted as a column — and a `reports:` entry declares `scope: all` or a stage name, emitted as `<alias>."<STATUS FK>" IN (<stage ids>)` ANDed onto its filter. With the nomenclature classified, an **aggregating** report **defaults to `live`** unless its dimensions/`filter` already reference the status, so a draft or voided document stops silently inflating every total (an existing model is byte-identical until it adopts `stage:`). Every site that names a status — `transitions[].from`/`setStatus`, a relation's `init:`, `setRelationField` `value:`, `abortOn.status`, a check's `status`/`setStatus`, `immutableWhen`, a posting's `event.when`, a report's `filter` — additionally accepts the **seeded name**, resolved to the id on the raw YAML tree before the typed mapping: an id is positional, so inserting a status mid-nomenclature used to silently retarget every guard authored against the old numbering (how a red-storno posting guarded on `Status == 8` stopped matching a Void that writes 9, leaving the ledger with a receivable for a document that no longer existed). A cross-model nomenclature can be neither stage-scoped nor named (its seeds live in the owner model) and says so; and when a lifecycle-carrying aggregate has neither a scope nor a status predicate nor a classified nomenclature, Generate emits a **warning** — now shown in the Intent Editor's own strip, not only the Builder shell's. Details in the engine-intent guide's lifecycle bullet.
-
-**The glue event axis: process-step events + non-HTTP inbound ([#6537](https://github.com/eclipse-dirigible/dirigible/issues/6537)):** a `notifications`/`integrations` `event:` binds either an entity lifecycle event or a **process step** — `onStepReached`/`onStepCompleted: { process, step }`. The step half adds no second delivery mechanism: `BpmnIntentGenerator` inserts a generated `JavaDelegate` at the step boundary (before the step for *reached*; after the writer/setter for *completed*, carrying the step's `next`) which loads the process's **trigger entity** by the id in the clear-D context and publishes its JSON on the entity's own topic plus a step suffix (`-step-<process>-<step>-reached|completed`), deferred to after commit — so the consumers are generated unchanged and every recipient path, `{placeholder}`, guard and forwarded body reads exactly as for a lifecycle event (`StepEventSupport` owns binding → entity → topic → emitter, deduplicated per moment). Rejected at parse: an unknown process/step, a step kind with no observable moment (only `userTask`/`serviceTask` have one), a process without a trigger. Alongside it, `inbound[]` declares **exactly one arrival** — `path:` (the `@Controller` webhook), `source: { queue | topic }` (a self-describing `MessageHandler`), or `source: { folder, cron }` (a `JobHandler` polling the drop folder: one record or an array per file, a file touched in the last few seconds is left for the next tick, every read file moves to `processed/`/`failed/`). All three save through the same generated repository — the arrival is a transport, not a second data path; a folder is polled, never watched, hence the mandatory cron there and its rejection elsewhere. **Mapping on arrival ([#6769](https://github.com/eclipse-dirigible/dirigible/issues/6769)):** deserializing the payload straight into the entity only works when it already *is* the entity, so an arrival may declare `accept: { type, version }` — a gate whose misses are **acknowledged and ignored** with a warning (202 on a webhook), never failed into redelivery — and `map:`, projecting envelope keys onto the record's own, where a value may be `{ lookup: <Entity>, by: <uniqueField>, from: <envelopeKey> }` resolving a **business key to a relation** (the requirement that alone forced a hand-written consumer). A non-unique `by:` is refused at Generate (it would silently pick one of several rows) and a lookup matching nothing **rejects** the arrival rather than storing a null FK; `ArrivalSupport` pre-renders the gate and each typed conversion, both keys work on all three arrivals, and omitting them generates byte-identically. **The departure half ([#6767](https://github.com/eclipse-dirigible/dirigible/issues/6767)):** `outbound[]` binds the same axis and emits on a queue or a topic — `to:` names exactly one of `queue`/`topic`, `payload:` is the same declared envelope `integrations:` takes, and the generated `<Name>Publisher.java` is a `MessageHandler` **subscribed to the record's own event topic** that re-publishes through `sdk.messaging.Producer`; because it is a subscriber the write is already committed, so a failed publish is logged and never fatal (no outbox, no exactly-once, no ordering — stated, not implied). The destination name is passed to the platform verbatim, so a departure inherits the `global:` external-contract marker ([#6766](https://github.com/eclipse-dirigible/dirigible/issues/6766)): unmarked names stay application-owned and tenant-prefixed, a `global:` one addresses another deployment.
-
-**The enrichment channel (`phases:` + `onPhase`, [#6929](https://github.com/eclipse-dirigible/dirigible/issues/6929)):** a value a listener computes AFTER the insert — a moving-average cost, a snapshot column, an external lookup — must be written back **event-silently** or it re-fires every onUpdate consumer of a change the user never made; so it published nothing at all, and a declarative consumer of that value had no moment to bind. Bound to `onCreate` it RACED the enrichment (two listeners on one topic have no order — each `MessageHandler` is its own durable subscriber, and there is no priority anywhere), and posted a balanced-looking journal entry for a null amount with parse, generation, compile and publish all green. The fix is a CHANNEL, not an ordering contract the broker cannot keep: an entity declares the moments it announces (`phases: [costed]`), the Java DAO template emits one **`announce<Phase>(id, values)`** per phase — `updateProperties` with the phase's own topic, so the enrichment and its notice ride ONE write into the outbox and commit together — and any glue consumer binds `event: { onPhase: <Entity>, phase: <name> }`. The generated method is the point: a hand-typed topic string reproduces exactly the silence being removed, a mistyped `announceCosted` is a compile error. Accepted by `postings:` (the driver), `notifications:`, `integrations:`, `outbound:` and an event-driven `generates:`, with the `when:` guard optional there (the phase already IS one moment); deliberately not by a process `trigger:`, a `wait` or `resolves:`. Refused at parse, each because it is otherwise silent: a phase that is not a lower-camel identifier, one named after a platform channel (`updated`/`deleted`/`transitioned`/`rekeyed`), a duplicate, a `phase:` key on another axis, and a binding naming a phase the entity does not declare. Details in the engine-intent guide's phases bullet.
-
-**Event-driven create-from (`generates` + `event:`, [#6711](https://github.com/eclipse-dirigible/dirigible/issues/6711)):** a `generates` entry may declare `event: { onTransition: <from>, when: "<Status> == <status>" }` (guard mandatory) or `{ onCreate: <from> }` and mint the follow-up **document — header AND items** by itself when the source reaches a state, instead of waiting for the button (`posts` is event-driven but emits flat rows and cannot reference the new header). The `map` entry copying the source's key IS the back-reference and therefore the **at-most-once** guard, derived rather than declared twice; the button is dropped unless `button: true`, and both triggers share ONE generated create-from (a new `GenerateOnEvent.java.template` listener calls `<X>Generate.create(id)` and carries no mapping of its own). Details in the engine-intent guide's `event:` bullet.
-
-**Declarative step resilience (`retry:` / `onError:` / `{error}` / `vars:`, [#6762](https://github.com/eclipse-dirigible/dirigible/issues/6762)):** a `delegate:` service task may declare `retry: { count, every }` (a Flowable failed-job retry cycle, `R<count+1>/<every>` — the R number counts TOTAL attempts) and `onError: <step | end>` (an error boundary event routed like a decision branch). The boundary only fires on a `BpmnError`, so `engine-bpm-flowable`'s `ResilientClassDelegateFactory` converts the FINAL failed attempt (mirroring `JobRetryCmd`'s arithmetic) into the caught `INTENT_STEP_FAILED` error, publishing the failure message as the `__errorMessage` variable — which a `setField` step on the error route reads via the whole-value `{error}` token. Process-level `vars:` + step `produces:`/`uses:` declare step data (an undeclared name is a parse error) and `clearAfter: <step>` removes a value — a generated credential — from the instance data once that step completes. v1 is delegate-only (parser-enforced); absent keys generate byte-identically. Details in the engine-intent guide's step-resilience bullet.
-
-**The general platform line this enshrines:** authoring artifacts (`.edm`, `.model`, `.form`, `.report`, `.intent`) get **workspace editors + an explicit Generate**; only runtime artifacts (`.roles`, `.bpmn`, `.csvim`, `.table`, jobs, listeners, …) get **synchronizers**. Applying the synchronizer hammer to an authoring artifact generates into the registry where no modeler, Projects view, or template can use it — that mistake was made once and reverted; the inventory of synchronizers (grep `extends BaseSynchronizer`) deliberately contains no authoring formats.
-
-## Model-to-code generation is Java (`ide-template`)
-
-Turning a model file into generated artefacts — the "Generate from EDM / model" step every template
-rides on — runs entirely in Java, in `components/ide/ide-template`
-(`ModelGenerationService` → `ModelGenerator` / `GlueGenerator` / `ModelParameterProcessor` /
-`ModelTemplateAdapters` / `ModelTemplateRenderer`). The endpoint is
-**`POST /services/ide/generate/model/{workspace}/{project}?path=<model>`** with body
-`{template, parameters}`; the older JavaScript path (`generate.mjs` + `generateUtils.js` +
-`parameterUtils.js` under `service-generate`) was migrated and **deleted** — see
-[`GENERATION_UTILS_JAVA_PLAN.md`](GENERATION_UTILS_JAVA_PLAN.md) §6-§7. Things to know before touching it:
-
-- **Template descriptors are still JavaScript.** Each `template-*` module exports `getTemplate()`
-  (sources + parameters), which the Java pipeline reads through
-  `GenerationService.getTemplateMetadata` (a GraalJS call per template). Their `generate()` functions
-  are gone: the per-template pre-logic lives in `ModelTemplateAdapters`, keyed by template id, and a
-  template the pipeline does not know is **refused by name** rather than half-generated. Add a
-  template → add its adapter entry.
-- **Every number in the parameter graph is a `Double`** and an absent key is not a null one
-  (`ModelValues.putNumber` / `remove`) — the graph reaches the engines through a `Map` deserialization
-  that types every JSON number as `Double`, so `minLength` renders as `0.0` and always did.
-- **Write JSON with `JavaScriptJson`, not Gson**, for the `.gen` descriptor and the translation
-  catalogs: Gson drops null keys, escapes HTML and writes `6.0` where the descriptor needs `6`.
-- **The Mustache engine writes into the parameter map it is handed** (it adds an indexed twin of every
-  collection), so `ModelTemplateRenderer` copies the context per invocation. Without that, the
-  artefacts land in the `.gen` descriptor, which is re-read on the next regeneration and accumulates.
-- **The intent Generate is one call**: `IntentGenerationService` writes the model files and then runs
-  the `.settings` recipes through this pipeline itself, reporting each one's outcome in
-  `codeGenerations` (`generated`, plus `error`). No client replays a plan any more.
-- `ModelGenerationIT` is the regression harness (it replaced the JS-vs-Java parity harness): every
-  template renders, twice, with the descriptor and the cross-project entity extension asserted.
-
-## Harmonia runtime UI (`template-application-ui-harmonia-java` + `template-form-builder-harmonia`)
-
-The runtime UI stack for generated applications: they render as a self-contained **Alpine.js + Harmonia SPA** (client-routed by Pinecone in hash mode, no iframes/`postMessage` hubs), served at `/services/web/<project>/gen/<model>/index.html`, talking to the **reused** generated Java REST controllers over a `fetch` client. The AngularJS IDE is untouched; the application layer now ships this stack only. `template-application-ui-harmonia-java` (registered on `platform-templates` as "Application - UI (Harmonia) - Java") emits the view types (list, manage, setting, master-detail, reports) + built-in **Process Inbox** (`/inbox`) and **Documents** (`/documents`) shell sections + inline process-task surfacing; `template-form-builder-harmonia` ("Harmonia Generator from Form Model", extension `form`) is the runtime form generator. The whole stack — Alpine 3.15.11, Harmonia 2.6.0, Lucide 1.8.0 — is embedded as **webjars** via `components/resources/application-core` (report charts use Harmonia's own native `x-h-chart-*` SVG charts; the `chart.js` webjar was dropped with the AngularJS dashboard shell) (incl. Pinecone Router — `org.webjars.npm:pinecone-router`, served version-less at `/webjars/pinecone-router/dist/router.min.js`; it was vendored until the 7.5.2 webjar existed). Developed on PR [#6078](https://github.com/eclipse-dirigible/dirigible/pull/6078).
-
-**Component reference:** the full codbex-harmonia directive catalog (all `x-h-*` components incl. the `x-h-select` combobox contract, theming, layout) lives **upstream** — the docs site <https://codbex.com/harmonia/> and the agent-readable skill <https://github.com/codbex/harmonia/blob/main/skills/harmonia/SKILL.md> (formerly mirrored in-repo under `reference/harmonia/`; that copy was removed to avoid drift — always consult the upstream, version-matched to `harmonia.version` in the root `pom.xml`). [`.../reference/alpinejs/`](components/template/template-application-ui-harmonia-java/reference/alpinejs/) still covers the Alpine patterns (routing, page components), mirrored from `codbex-athena-app`, the reference app this stack was adopted from. Read them before changing Harmonia markup.
-
-**Detailed guides:** [`components/template/template-application-ui-harmonia-java/README.md`](components/template/template-application-ui-harmonia-java/README.md) (the SPA shell, view-type parity checklist, the master-detail detail registry, process-tasks store) and [`components/template/template-form-builder-harmonia/README.md`](components/template/template-form-builder-harmonia/README.md) (the neutral `formController(ctx)` contract). The repo-root [`HARMONIA_RUNTIME_PLAN.md`](HARMONIA_RUNTIME_PLAN.md) is the design doc + implementation status. **Gotchas that already burned someone — read before changing the templates:**
-
-- **REST path must use the Java-sanitised names.** `restBase` is `/services/java/<project>/gen/${javaGenFolderName}/api` and each page's `apiPath` is the **relative** `/${javaPerspectiveName}/<Entity>Controller`; the fetch client prepends `restBase` exactly once. Use `javaGenFolderName`/`javaPerspectiveName` (e.g. `sales-order` → `sales_order`), **not** the raw `genFolderName`/lowercased perspective — the generated backend lives under the sanitised Java package. (Phase 0/1 only passed because `edm` needs no sanitising.)
-- **`{ baseUrl: '' }` means "URL is absolute, prepend nothing".** The fetch client checks `opts.baseUrl !== undefined`, not truthiness — passing `''` with a relative path (or omitting it with an absolute path) is the classic doubled-URL bug (`/api/services/java/.../api/...`). Entity pages use a relative `apiPath` and **no** override; absolute URLs (relationship dropdowns, the detail registry) pass `{ baseUrl: '' }`.
-- **Date/time widgets need conversion both ways.** The form `toPayload()` turns an HTML `date`/`datetime-local` value into a full ISO instant (`…Z`) so a Jackson `java.time.Instant`/`Timestamp` field binds (empty→`null`, a bare `TIME` passes through); `toDateInput()` slices the backend's ISO value back to what the widget expects on edit. Mirrors the AngularJS stack's `new Date(value)`.
-- **Master-detail is registry-driven.** A master page renders one `detailPanel` per `App.detailsFor(<master>)` entry; each detail self-registers via `App.registerDetail(...)` (relative `apiPath`), so masters never enumerate details at generation time. The detail list filters via the controller's `?<masterEntityId>=<id>` query (built into the reused rest-java controller for `*_DETAILS` layouts).
-- **The `.form` runs the existing AngularJS `code` via compat shims, and the page is self-contained.** `template-form-builder-harmonia` runs the `.form` `code` as the body of `formController(ctx)` (`ctx.{model, params, http, task, notify, close}`) and defines `$scope`/`$http`/`NotificationHub`/`DialogHub` shims so intent-generated AngularJS `.form` code runs **unchanged** (no migration needed). The page loads only `form.js` + its own minimal fetch client (no `window.App`), because a BPM task form opens standalone in an iframe where the SPA shell assets are absent — an earlier `../../js/...` reference 404'd and left `App` undefined.
-- **A standalone page must bootstrap `App.config.projectName` before loading `i18n.js`, or every module-authored label silently stays English.** `i18n.js` reads the project namespace off `App.config.projectName` — which only the SPA shell sets — and without it fetches just the platform `application-core` chrome catalog, so the page's own `<tprefix>.t.*` keys never resolve. The failure is invisible: the baked English literals render, no console error, and every shell page around the iframe IS translated. Both standalone pages (the report page and, since [#6692](https://github.com/eclipse-dirigible/dirigible/issues/6692), the task form) therefore set it in a one-line inline script before the `<script src=".../services/i18n.js">`. Two more rules the task-form conversion paid for: a value that is MATCHED against data (a status step's `label`, compared to the record's status) stays untranslated and gets a separate translated `title`, and an authored label must be escaped where it is interpolated into a `T()` call — **both the literal and the key derived from it**, since `translationId` strips only spaces and `_ . :`, so an apostrophe would close the JS string and break the whole Alpine expression.
-- **Intent glue handlers are self-describing `@Component`s, not class-level `@Listener`/`@Scheduled`.** Those SDK annotations are `@Target(METHOD)`; the rollup/notification/integration/job templates in `template-application-events-java` were converted to `@Component implements MessageHandler/JobHandler` with `destination()`/`kind()`/`cron()` (matching the Trigger template) — class-level use fails `javac` with "annotation interface not applicable".
-- **The full-stack model template MUST merge the schema layer.** `template.js` = `template-application-schema` + REST-java + Harmonia UI. The client-Java `JavaEntityManager` only *registers* an `@Entity` against an existing table — it never CREATES one; `TableCreateProcessor` (the schema sync) does. Drop the schema and a freshly generated app has **no tables** → CRUD + CSVIM seeds fail ("Table metadata was not found for table [...]"). It only *looked* fine when a prior AngularJS/schema generation had already created them ("table kept in place").
-- **Process trigger writes its process stamp via a targeted update (no event, no full row).** Starting a process on `onCreate` writes the instance id back; doing it through the normal `update()` republishes `<entity>-updated` and spuriously fires every onUpdate reaction (e.g. the member-email notification fired the instant a loan was created) — and even the silent `updateWithoutEvent()` was a **full-row merge of the trigger's stale snapshot**, which raced concurrent writes (line items recalculating the header totals milliseconds after create, a start-step status set) and silently reverted them. The trigger writes it with one `repository.updateProperties(id, {"ProcessIds": …, "ProcessId": processId})` — an SDK `JavaRepository`/`JavaEntityStore` HQL mutation touching only the named columns; no audit stamping, no events, nothing else to clobber, while the generated repository's own bookkeeping on that path (the `history:` trail entry attributed to SYSTEM, the stored `label:` Name) still runs. What must NOT run is a gate that can REFUSE it: the generated repository skips `enforceChecks` for a targeted write that touches only **platform-owned** columns (`SYSTEM_PROPERTIES` = `ProcessId`, `ProcessIds`; `touchesAuthoredColumn(values)`), because a document check has no opinion about which process handles the record and the instance is already running by then — an unbalanced or item-less document that records its process beats one that does not. Everything a person or a workflow authors keeps the gate. **Everything that can happen before the start does**, because the stamp IS the at-most-once guard and the two commits are independent: the minted `businessKeyStrategy` value is persisted BEFORE `Process.start` (the instance is started with that key), and every process variable — the `__entityUrl`/`__entityId` locators, the FK locators, `__personalUser` — rides the **start payload** rather than a `setVariable` afterwards (they are all known up front; a process without a wait state runs to its end inside `start`, and a `setVariable` against a finished instance throws). The write-back is then the only post-start step: a `null` instance id (the platform swallows a failed start) is logged and not written, and if the write does not land — the row was deleted, or it threw — the just-started instance is **cancelled** (`Process.cancel`) and the failure re-thrown, because a running instance no record points at is invisible to the application while its user tasks still reach an inbox (#6815). The trigger guard is **per process**: `ProcessStamps.has(entity.ProcessIds, "<Process>")` over the `ProcessIds` column's `Process=instanceId` pairs (#6862). A record can legitimately be the subject of several flows — "on create, identify it; when identified, run dunning" is what the `onTransition` trigger axis invites — and the old record-wide `ProcessId != null && !isBlank()` guard made every process indistinguishable from every other, so the follow-up flow silently never started for a record the first flow had already stamped. `ProcessId` stays as the most recent instance, which is what the task UI correlates on; a `wait` and an `abortOn` read their OWN instance out of `ProcessIds` (`ProcessStamps.idFor`) instead. A record carrying only the legacy `ProcessId` counts as already handled — today's behaviour, so an upgrade cannot start a second instance of a flow that is already running. An empty string still must not count as "already started" (a form sends one for an untouched system field).
-- **Documents/CMS path contract (`/services/documents`, `engine-cms`'s `DocumentsEndpoint`).** Java since the GraalJS backend was retired — the old `/services/js/documents/api/documents.js` is **gone**, and with it the `?path=/` 400 quirk (`/` now lists the root, as does omitting the parameter). Still true: the CMS query layer does **not** decode an encoded slash, so build `?path=` with **literal slashes** — encode each segment, not the whole path (`p.split('/').map(encodeURIComponent).join('/')`); a blanket `encodeURIComponent` turns `/`→`%2F` and every subfolder/file 400s. Rename is `PUT {path,name}`; delete is `DELETE` with a JSON body of absolute paths; create a folder with `POST /folder {parentFolder,name}`; upload is multipart under the part name `file`; preview/download are `GET /preview|/download?path=`; zip is `GET|POST /zip?path=`. `__internal` is never listed or addressable (403), and `__EXPORTS` needs ADMINISTRATOR/OPERATOR. Both UIs (the AngularJS `documents/js/documents.js` perspective and the shared Harmonia `application-core/shell/.../documentsPage.js`) speak exactly this contract; content types can be overridden by contributing a `DocumentContentTypeResolver` bean (the Java replacement for the `ui-documents-content-type` extension point).
-- **Edit forms: match the value to the input shape (dates + comboboxes).** The Java REST controller serializes `java.time` via Jackson as **arrays** (`LocalDate` → `[y,m,d]`, `LocalDateTime` → `[y,m,d,h,mi,s,ns]`) and `Instant` as a **numeric epoch** — NOT ISO strings — so the form's `toDateInput()` handles arrays/numbers/strings (a naive `String(v).slice()` yields garbage → empty date controls on edit). And a relationship FK comes back as a **number** while an option's `data-value` is a string (HTML attribute), so the value must be **stringified on load** (`form.X = String(record.X)`) or the `x-h-select` matches no option and renders empty on edit — the same `String(...)` the codbex-athena-app edit pages use.
-- **Combobox = the Harmonia `x-h-select` contract; the Harmonia skill is the primary source of truth** (<https://github.com/codbex/harmonia/blob/main/skills/harmonia/SKILL.md>, version-matched to `harmonia.version` in the root pom) — existing code is only an example, and an example that contradicts the skill is wrong. `x-model` on `x-h-select-input` holds the VALUE (the option `data-value`, a string); the directive hides that input and appends a visible `button[role=combobox]` trigger (`data-slot="select-input"`) showing the matched option's label — Selenide finders and CSS target the button, and note the search's generated input also carries `role=combobox`. Use `data-filter="contains"` + an in-dropdown `x-h-select-search` for searchable pickers; options go via `x-for` with `:data-value="String(opt.value)"` **inside an `x-h-select-list`** under `x-h-select-content` — the list owns the `role=listbox`, padding and vertical scrolling (the content is `overflow-hidden`), so options placed directly in the content render clipped with no scrollbar. Clearing a selection is `data-clearable="true"` on `x-h-select` (re-clicking the selected option clears it). A `disabled` `x-h-select-input` disables the trigger with it, but the generated form still renders a **context-locked** parent FK as something else entirely (`<template x-if>` around the whole `x-h-select`) — showing the referenced record's label beats a greyed-out combobox.
-- **A parent FK implied by the navigation context renders locked, not free (#6551).** When a child is created or edited from inside its parent — a master's detail panel, a create-from flow — the opening URL names the parent FK (`?<Fk>=<id>`), and the generated manage form renders that relation as the referenced record's label, read-only (`isContextLocked(name)` / `contextLabel(value, options)` on `baseFormPage`), never as a dropdown that could re-point the record mid-flow. The shared `detailPanel` therefore carries the master FK on **edit/preview** as well as create — on edit it presets nothing (the record is authoritative), it only declares the context. A form opened with no such param (the entity's own top-level create) keeps free selection. This supersedes #6513's blanket hide of `relationshipType="COMPOSITION"`: showing which parent the record is filed under is the point; hiding the field only removed the affordance.
-- **Theme goes through Harmonia's own colour-scheme API — do not hand-toggle `.dark`.** `harmonia.min.js` manages the `.dark` class itself from `window.Harmonia.get/setColorScheme('light'|'dark'|'auto')`, persisted to localStorage key `codbex.harmonia.colorMode`; its default is `auto` (follow the OS). The shell's top-right switch (`appShell.js toggleTheme()`) calls `Harmonia.setColorScheme`, and a head bootstrap defaults the key to `light` on first run. Because **every** page loads harmonia.min.js and reads the same key, the shell and the standalone form/report iframes all theme consistently — this is why the task form no longer renders dark on a light shell (an earlier custom `dirigible.harmonia.theme` key + manual `.dark` toggle only fixed the shell, not the iframes). Settings is pinned to the **sidebar footer** (bottom-left, like codbex-athena-app); Reports is a single entry **discovered at runtime** (a `reports` store walks the project registry tree for `*/reports/*/index.html`, since intent reports are standalone pages in a separate gen folder the shell can't see at generation time). The intent recipe defaults (`IntentSettings.scaffold`) point model/form/report at the Harmonia templates; glue stays the neutral client-Java template.
-
-- **Velocity vs Alpine `$` is the #1 trap in the Harmonia shell templates.** The shell's `index.html.template` and `dashboardPage.js.template` are **generated via Velocity** (they use `$models`/`$entity`/`$appIcon`), and Velocity parses `$`-references **everywhere — including inside HTML comments and JS string bodies**. An Alpine magic like `$store`/`$notifications`/`$nextTick` is fine as a *bare reference* (undefined → Velocity passes it through literally), but the moment it's followed by a **method call with args or trailing statements** Velocity tries to parse it and the generation 500s with `Encountered "..."`. Three real burns: `$store.processTasks.openTask(n.task); n.unread=false` in an `@click` (fixed by moving the logic to an `appShell.openNotification(n)` method and calling that), `$notifications.add({ template:'toast', data:{ message, variant } })` **in an HTML comment** (Velocity choked on `{ message,…}` — reworded the comment), and `$store...filter(r => r.dashboard !== false)` in a getter (escaped via `#set($dollar='$')` + `${dollar}store`, the same trick `report.js.template` uses for `$limit`/`$nextTick`). Rule: in a Velocity-generated file keep `$store.x` to bare refs / no-arg calls, escape with `${dollar}` for anything richer, or move it into a copied (non-Velocity) JS file / an appShell method.
-- **Put cross-scope shell state in an Alpine *store*, not the `app` component.** `theme` lived on the `app` component (`x-data="app"`) and its toolbar `x-show="theme !== 'dark'"` threw **"theme is not defined" on every load** — eager `x-show` evaluation in a scope Alpine hadn't resolved yet (other `app` props on the same toolbar were fine; only the eager ones failed, intermittently). Moved it to `$store.theme` (`{ value, toggle() }`, backed by `Harmonia.set/getColorScheme`); stores resolve from any scope at any time, like `$store.notifications`/`currentUser`/`reports`/`processTasks`. (This **supersedes the `appShell.toggleTheme()` note above**.)
-- **Embedded iframes (report/form preview, task form, dashboard report tiles) only theme at load.** Harmonia applies the shared `codbex.harmonia.colorMode` key when the iframe loads; toggling the shell theme afterwards left them stale until a full refresh. Fix in **every** standalone/embeddable page — `report-file/index.html`, form-builder `ui/index.html`, **and the per-project Harmonia shell `ui/shell/index.html` itself** (it is embedded in the application-shell iframe and in the FK "Add new" dialog, and hosts the list/manage/master-detail/document views, so the one listener makes all of them follow a parent theme switch): a `storage` event listener (it fires in same-origin iframes when the **parent** changes localStorage) that calls `Harmonia.setColorScheme`. **Do NOT gate on `Harmonia.getColorScheme() !== scheme`** — it reads the same key which already holds the new value, so it always skips and nothing re-applies; track a module-level `lastApplied` scheme instead (re-apply once, no echo loop).
-- **An icon carrying an Alpine directive must be `<svg x-h-lucide>`, never `<i>`.** Harmonia refuses the combination *by throwing* — `"x-show" cannot be used on a <i> placeholder, because the element is replaced by the rendered svg and the binding would be lost` — and the exception is **not local to the icon**: it aborts the enclosing `x-for`, so every item after the first renders with no name, no id, no icon and unevaluated bindings. That is how the tenant picker (`security-oauth2/.../static/tenant-selection.html`) shipped a list that showed only its first tile, invisible until it was rendered with real data. Two corollaries from the same page: prefer `x-if` over `x-show` on an element Harmonia also styles (they fight over `display`), and give a branding logo an `@error` handler so an unresolved one hides instead of leaving the browser's broken-image glyph.
-- **`x-show` only hides — Alpine still evaluates the inner bindings.** The master-detail detail pane is `x-show="selected"`, but before a row is selected `selected` is null and `x-text="displayValue(selected.Email)"` threw `Cannot read properties of null`. Use optional chaining (`selected?.<field>`) in the property panes (list/manage/master). Same reason the report-tile preview iframes are `<template x-if>` not `x-show`.
-- **Split-panel sizing is `data-size` (a `%` or px), NOT `data-default-size`** — `data-default-size` isn't referenced anywhere in harmonia 2.1.0 (silently 50/50). Both panes need it (`data-size="60%"` + `data-size="40%"`). To collapse a pane until needed (detail-pane-until-selection), bind `:data-hidden="!selected"` on the panel — the same mechanism the sidebar's collapse uses.
-- **`x-h-toolbar-title` bakes in `whitespace-nowrap text-ellipsis overflow-hidden`** — in a flex toolbar an entity title shrank to "Bo…"/"Mem…". Add `class="shrink-0"` to entity-name titles (list/manage/master/form/report) so they keep their natural width; leave the *dynamic* inbox titles truncating.
-- **The shell is richer than the original skeleton (all model/runtime-driven):** a **home Dashboard** (`/` and `/dashboard`, `dashboardPage` + `_dashboard.html`) with report-attached KPI widget tiles (`reports[].widget`) + custom widget tiles (`widgets:`) and a per-report preview tile (the report page in `?preview=1` mode — toolbar/pagination hidden, 5 rows) — there are no auto per-entity record-count tiles; **sidebar sections** Application / Entities / **Reports** (one entry per runtime-discovered report, selecting sets `$store.reports.selected` and opens it embedded on `/reports`); a route-derived **breadcrumb** (`navLabels` from a generated `window.__harmoniaNav` map so the entity crumb matches the sidebar); and a top-right **user menu** (name from `/services/js/platform-core/services/user-name.js`, logout → `/logout`), **notifications bell** (the `notifications` store; `processTasks.syncTasks()` surfaces BPM tasks as bell items, the store polls every 30s + on `pinecone:end` so they appear without a manual refresh), and the **theme** switch. Settings still pinned to the sidebar footer.
-- **`widgetSize` is now a plain integer column count (3/4/6/12), not a Fundamental CSS class.** The entity editor stores the number; Harmonia maps it to `grid-column: span N` (12 → `col-span-full`) on a 12-col form grid. Migration caveat: old `.edm` files with the legacy `fd-col-md--2 fd-col--3` string render a broken width class.
-- **Form typography conventions (generated views).** Read-only / system fields (`isReadOnlyProperty` — `ProcessId`, audit columns, `uuid`, any `readOnly: true` field — and audit) render in a headerless **`x-h-card`** above the action buttons (a framed details block like the master-detail card, no title), NOT as editable inputs: `x-h-card` > `x-h-card-content` with a `grid-cols-1 sm:grid-cols-2 gap-x-4 gap-y-2`; each field a `vbox gap-0` with label `class="text-xs text-muted-foreground"` and value `class="text-sm"`, shown on edit and only when the value is populated. Wired in `manage/form-view` + `document/document-view` (master-detail reuses the manage form). **Document layout roles.** In a document (header-items) entity, a field with intent `documentTitle: true` → `widgetType="DOCUMENT_NUMBER"` renders in the form **title** (`'<DocLabel>'.toUpperCase() + ' ' + form.<number>`, e.g. "SALES INVOICE 00001231"), and a to-one relation with `documentStatus: true` → `widgetType="DOCUMENT_STATUS"` renders as a read-only **`x-h-badge` pill** in the title bar (text resolved from its dropdown options, colour from `statusVariant(text)` — a keyword→variant map: draft→outline, approved/accepted/active→positive, issued/sent→information, cancel/reject→negative, pending→warning). Both are pulled from the editable grid; the status keeps its dropdown lookup metadata so the pill can resolve the id→name. For secondary/muted labels (e.g. the document totals footer) use **`text-secondary-foreground`**, not `text-secondary` (the bare token is the surface colour, not the on-surface text colour — labels using it render near-invisible).
-- **The model-independent shell runtime is SHARED, not copied per project.** It lives once at `/services/web/application-core/shell/` (`components/resources/application-core/.../application-core/shell/`: `app.js`, `services/*`, `stores/*`, `components/layout/appShell.js`, base/page components, `css/app.css`, and the Inbox/Documents/Reports/notfound views). The generated per-project shell and the application shell both load it from there by absolute URL; `template-application-ui-harmonia-java` only **generates** the model-specific files (`index.html`, `config.js`, `dashboardPage.js`, `_settings.html`, `_dashboard.html`, per-entity pages). Do NOT re-add per-project copies of the shared files (`shell.js` no longer emits them). PR [#6094](https://github.com/eclipse-dirigible/dirigible/pull/6094).
-- **A BPM task's name travels with its translation key — the shell never derives one.** The Inbox, the notification bell and the app-wide task-form dialog are shared by every deployed app, so they cannot know which module's catalog holds a task's name: an Approve button stayed English on an otherwise fully translated app (#6522). So the generated `.bpmn` declares its module's catalog once, on the `<process>` element (`<flowable:property name="taskLabelCatalog" value="<project>:<model>-model.processes"/>`, minted by `IntentNaming.processTaskCatalog`), and `BpmInboxEndpoint` serves every task a `nameKey`/`processDefinitionNameKey` composed from it plus the BPMN id — which IS the authored step / process name, i.e. exactly how the catalog keys it. Read off the deployment-cached `BpmnModel`, resolved once per definition per request. Everything is decided at generation time; the client only renders `T(task.nameKey, task.name)` through the one rule on the `processTasks` store (`taskName` / `processName` / `taskLabel`) and adds the namespaces its tasks reference via `AppI18nAddNamespaces`. A process that declares no catalog (a hand-authored BPMN) keys nothing and renders the raw BPMN name, as before. **Do not reintroduce the per-project `processTaskKeys` reverse map** that `config.js` used to bake — it could only ever translate tasks from the hosting project, and two mechanisms for one label is how the shell surfaces got missed in the first place.
-
-### Application shell (`resources-application`) — the pure-Harmonia app launchpad
-
-`components/resources/resources-application` (`dirigible-components-resources-application`), served at **`/services/web/application/`**, is the shell **for the application layer** — the IDE stays AngularJS + BlimpKit, but the app layer is pure Java + Harmonia (the AngularJS Dashboard shell it replaced, `resources-dashboard`, was removed in #6589). It reuses the shared runtime for the built-in Dashboard/Inbox/Documents/Reports pages (Pinecone routes into `#app`) and aggregates the **`application-perspectives`** extension point for the domain apps, hosting each one's generated SPA in an embedded iframe (`?embedded`). It shows **named perspective groups only**, so the platform's AngularJS *utility* perspectives (e.g. `platformSettings` → `/services/web/perspective-settings/settings.html`, `ng-app="settings"`) are excluded — **never iframe an AngularJS perspective into the Harmonia shell, it won't bootstrap standalone**. Each generated app contributes one per-entity perspective to `application-perspectives` whose `groupId` is the intent entity's `group:`; the groups are defined once in a dedicated navigation-groups project (the codbex pattern). Wired into `components/pom.xml` (modules + dependencyManagement) and `group-ui`.
-
-**A perspective the aggregator cannot place is never dropped, and never silently** (issue [#6646](https://github.com/eclipse-dirigible/dirigible/issues/6646)). `platform-core/extension-services/modules/perspectives.mjs` pushes perspectives into groups **by `groupId`**; an id matching no group used to be discarded, so the group rendered empty — indistinguishable from "no module contributes here", with no console warning and no log line anywhere (the *authored-but-silently-unconsumed* class). Now: the unmatched id is `console.error`-ed naming the perspective and the id, then placed in the extension point's **default group** — a group declaring `isDefault: true` — else the platform's `undefined-group` catch-all, else handed back standalone for the shell to render. The **single-group shells** (`resources-personal` / `resources-partner` / `resources-admin`) declare their one group `isDefault: true`, so their generated perspectives (`ui/{my,partner,admin}/*-perspective.js.template`) deliberately declare **no `groupId` at all** — repeating a platform constant in every generated artifact is a coupling that can only drift, and the "My Work" → "Personal" rename proved it: every already-generated module kept `groupId: 'my'` and its personal pages vanished. `undefined-group` is deliberately **not** marked default, so a no-`groupId` perspective on `application-perspectives` still comes back standalone and the shells' catch-all "Other" section renders it (that branch now rescues **any** `kind`, not just `PRIMARY` — enumerating kinds is how `PERSONAL` fell off the end of the chain). `PerspectiveGroupAggregationIT` guards both placements; `IntentEmissionCoverageIT` asserts the perspective is **inside** its group, not merely present in the response.
-
-### Builder shell (`resources-builder`) — the conversational AI intent builder
-
-`components/resources/resources-builder`, served at **`/services/web/builder/`** (shell id `builder`, `.access`-gated to ADMINISTRATOR/DEVELOPER), is a standalone Harmonia shell where you **describe an application in plain language and publish it**. It adds **no backend**: it is a frontend orchestration over endpoints that already ship, reusing the shared `application-core` runtime (theme/notifications/branding/i18n) by absolute URL. One screen, so there is deliberately **no Pinecone router**.
-
-The loop: chat → `POST /services/ide/intent/agent` → **re-validate the proposal client-side through `POST /parse`** → auto-apply (no diff/Accept — the chat text is the narration) → the canvas redraws. **The agent answers 200 even when its proposal still fails validation** (the server's two repair rounds were exhausted, signalled only as trailing prose in `reply`), so the client-side re-validation is load-bearing, not belt-and-braces — an invalid proposal is shown as issues and never reaches the buffer. Project and file management are hidden: the project id is a slug of the intent's `name`, created lazily on the first accepted proposal and never renamed; every accepted proposal is auto-saved, so a reload restores from disk. Chat history is persisted **server-side** per `(tenant, project, surface)` and restored on open (the agent endpoint is stateless, so the transcript is a record the platform keeps, not browser state); the store appends one turn at a time and a failed append is carried by the next turn rather than breaking the chat.
-
-**The one button** (`js/services/pipeline.js`, the `publish` store) runs save → **Problems baseline** → `/intent/generate` (which generates the models AND the code from them in that one call, reporting each recipe's outcome in `codeGenerations`) → publisher → healthcheck poll + **Problems diff filtered to `/<project>`**. That diff is the only honest "published clean" signal — publishing is synchronous but reports nothing about what the synchronizers made of the artefacts, so a client-Java compile error or a failed CSVIM seed surfaces there and nowhere else. The success panel's "try it here" links are **discovered** (`platform-shells`, plus the app's own perspective path from `application-perspectives`) — never assembled from a guessed `gen/<model>` convention, which would 404 the moment a template changed its layout.
-
-Gotchas this shell paid for (all confirmed by `IntentBuilderShellIT`):
-- **Never put an Alpine binding on `<i x-h-lucide>`.** The plugin REPLACES the `<i>` with the rendered svg, so a binding would be lost — it throws instead, and the uncaught throw **aborts Alpine's walk over everything below it** (the toolbar rendered, the whole split pane did not). Use an `<svg x-h-lucide>` placeholder for any `:data-lucide` / `:class` / `x-show`.
-- **The idempotent creates answer `304`, and `response.ok` is 2xx-only.** `POST /workspaces/{ws}` and `.../{ws}/{project}` return 201 the first time and **304 NOT MODIFIED** afterwards, so a naive `!response.ok` throw makes the *second* save fail while the first succeeded. The fetch helper takes an `alsoOk: [304]`.
-- **The workspace may not exist at all** on an instance where the user never opened the IDE; creating a project inside a missing workspace answers 404, so `ensureProject` creates the workspace first.
-- The agent endpoint can make three upstream calls at 120s each — the client timeout is **7 minutes**, with a staged typing indicator.
-- **Ask `GET /services/ide/intent/agent/status` whether the assistant is usable, never a throwaway `/agent` turn.** The shell probes on load so an unconfigured instance says so before the user types; the status endpoint reads configuration only, so it costs no upstream model call (a probe that posted a real turn would burn an Anthropic round-trip on every page load of a *working* instance).
-
-The mxGraph rendering is **shared, not copied**: `editor-intent/js/intent-diagrams.js` exposes the framework-free `window.IntentDiagrams.render(model, host)` / `.dispose(host)`, extracted from the Intent Editor's controller and loaded by both (the shell by absolute URL). A standalone page must link **`platform-core/ui/styles/fonts.css`** or the glue cards' SAP-icon glyphs render as tofu. Tests: `IntentBuilderShellIT` — a `@Tag("smoke")` bootstrap check plus the full journey against a **local HTTP stub of the Anthropic upstream** (`DIRIGIBLE_INTENT_AI_BASE_URL`, the same override `IntentAgentServiceTest` uses in-process), so it needs no key and no network.
-
-### Monitoring shell (`resources-monitoring`) — the operations surface
-
-`components/resources/resources-monitoring`, served at **`/services/web/monitoring/`** (shell id `monitoringShell`, order 37, icon `activity`, gated to ADMINISTRATOR/OPERATOR/DEVELOPER by `monitoring.access`), answers "is the system healthy, and if not, what broke?" without opening the IDE. Same skeleton as `resources-my` / `resources-admin`: a pure-resources module over the **shared** runtime at `/services/web/application-core/shell/`, **no new backend** — every page reads an existing, role-gated platform endpoint. Six pages: **Overview** (health, readiness, artefacts in error, failed jobs, process incidents, DB-pool pressure, broker backlog — polled every 30 s, pausable), **Processes** (instances + the live BPMN diagram + the two triage actions, retry/skip), **Jobs** (list, execution log with the tenant column, enable/disable/trigger), **Logs** (the `/websockets/ide/console` live stream + the log files), **Messaging** (read-only), **System** (the build this instance runs + the JVM snapshot + session-local sparklines). Design docs: repo-root `MONITORING_SHELL_PLAN.md`; delivered on PRs [#6613](https://github.com/eclipse-dirigible/dirigible/pull/6613) (backend prerequisites), [#6614](https://github.com/eclipse-dirigible/dirigible/pull/6614) (shell + Overview) and [#6615](https://github.com/eclipse-dirigible/dirigible/pull/6615) (the remaining pages).
-
-Things worth knowing before changing it:
-
-- **The scope line is deliberate.** Deep and destructive tooling — SQL console, terminal, message purging, process-variable editing, tracing, **log-level changes** — stays in the Workbench permanently; each page links there instead of cloning it. Re-implementing a BPMN modeler or a data grid here means we overshot.
-- **Two backend prerequisites shipped with it** (#6613): `HttpSecurityURIConfigurator` now carries a **monitoring gate** (`/services/bpm/bpm-processes/**`, `/services/ide/{monitoring,logs,loggers,messaging-monitoring}/**`, `/websockets/ide/console`) matched **before** the DEVELOPER gate, aligning the URL layer with those controllers' declared `@RolesAllowed` — the rest of `/services/ide/**` and `/services/bpm/**` (workspaces, git, publisher, the BPMN modeler) stays DEVELOPER-only, and `HttpSecurityURIConfiguratorTest` guards the whole matrix including the ordering. And `GET /services/core/artefacts` (`ArtefactStatusEndpoint` in `core-base`) aggregates the `ArtefactService` beans — every synchronizer registers one, so the bean list *is* the inventory; it replaces depending on the IDE perspective's `artefacts.mjs` JS aggregator.
-- **Every read goes through `js/services/ops.js`**, and the aggregate pages wrap each source in `ops.soft(...)` so one unavailable engine degrades to a marked tile instead of an empty screen. The Overview's incident scan is one request per active instance (there is no bulk endpoint) and is capped at 50 — the page says so rather than silently reporting "no incidents".
-- **The BPMN diagram is the same visualizer the IDE uses** (`bpmn-visualization` webjar), loaded on first use (~1 MB — the Overview must not pay for it) and themed through Harmonia's own `--foreground` / `--input-background` / `--positive` / `--negative` variables. The server-side PNG endpoint stays a fallback: it is static and theme-blind.
-- **Known data issues, filed but not blocking:** job logs leak and clear across tenants ([#6606](https://github.com/eclipse-dirigible/dirigible/issues/6606)), tracing reads/deletes are cross-tenant ([#6607](https://github.com/eclipse-dirigible/dirigible/issues/6607)), `TracingFacade.disableTracing()` sets the flag to `"true"` ([#6608](https://github.com/eclipse-dirigible/dirigible/issues/6608)), `JobEndpoint.emailremove` is doubly broken ([#6609](https://github.com/eclipse-dirigible/dirigible/issues/6609)). v1 is an instance-level operator surface and shows the job-log tenant column until #6606 lands. The BPM/Flowable queries **are** tenant-filtered — no issue there.
-- **"Which build is this?" is answered from `/services/core/version`** — the same payload the Workbench's About window reads, in the `version` store (read once; a running instance never changes its build), rendered as the System page's **Build** card and condensed onto the sidebar footer, where every page shows it. The keys behind it (`DIRIGIBLE_PRODUCT_NAME` / `_VERSION` / `_COMMIT_ID`) ship **unfiltered** in `dirigible-commons.properties`, so until `build/application/src/main/resources/dirigible.properties` re-declared them (that module filters its resources and runs the git-commit-id plugin) every stock instance reported the literal `${project.version}` and the About window hid the row. A downstream distribution overrides the same three keys with its own `dirigible.properties`; the UI treats a value that still looks like a Maven placeholder as unknown.
-- **`MonitoringShellIT`** (`@Tag("ui")`) is the guard that matters: the Alpine-bootstrap failure mode (an Alpine binding on an `<i x-h-lucide>` aborts the walk) has no DOM or server-side symptom, so only a real browser catches it. Each page root carries a stable id (`monitoring-<page>-page`) so the assertions do not depend on what happens to be deployed.
-
-## Document templates (`parsers/document` + `engine-document`) — print to PDF
-
-A lightweight declarative document-template engine for printable business documents (invoice, order, receipt, ...), merged 2026-07-02 via PRs [#6118](https://github.com/eclipse-dirigible/dirigible/pull/6118) (parser library) and [#6119](https://github.com/eclipse-dirigible/dirigible/pull/6119) (platform arc). Four cooperating layers:
-
-- **`modules/parsers/document`** (`dirigible-parsers-document`, pure library, zero deps) — the XML-like DSL: hand-written parser (business-user lenient: raw `&` is literal, Mustache `{{...}}` survives verbatim, exact line/column errors), sealed `Node` AST (one record per tag + `CustomNode`/`TagRegistry.register` extension), layout primitives (`Measurement` `100/100px/50%/*/2*/auto`, `Alignment`), `DataBinder` (map-context `{{path}}` merge; `table`/`for` `source` lists expand to rows with row-scoped fallback; `if` truthiness; unresolved → empty; **`{{A|B}}` alternative operands** — first non-blank wins, left to right, the last one rendered whatever it holds, so an optional twin field never leaves a hole in a legal document; **floats print as `### ### ### ##0.00`** — the form pages' money pattern), and `XslFoRenderer` (bound layout tree → self-contained XSLT/XSL-FO stylesheet for the FOP `PDFFacade` — the platform's only PDF path). Grammar/EBNF + gotchas in the module README.
-- **`engine-intent`'s `PrintIntentGenerator`** (@Order(800)) — Generate emits a standard `<Entity>.print` per document (header-items) master at the project root; `.print` is an intent-owned (scrubbed) extension. Data contract: `{{document.<PascalProp>}}` + `<table source="items">` with `{{<PascalProp>}}` cells.
-- **`components/engine/engine-document`** — the runtime: `PrintTemplateSynchronizer` (multitenant) seeds the published template into the CMS at `Templates/<Entity>/Print/en/standard.print` **create-if-absent** — user customizations uploaded via the Documents perspective are never overwritten, and deleting the artefact never touches the CMS; `PrintEndpoint` — `GET /services/print/{entity}/languages` (CMS language folders, `Locale` display names) and `POST /services/print/{entity}?lang=` (`{document, items}` JSON → parse → bind → XSL-FO → `application/pdf`). The **client supplies the data** it already loaded (no server-side entity fetching/auth forwarding); dropdown FKs arrive as display labels.
-- **Harmonia document view** — a Print button (edit-only, footer toolbar): one CMS language prints directly, several open a language dialog ("English" → en). Multilanguage = upload templates under more `Templates/<Entity>/Print/<lang>/` folders.
-
-**Detailed guide:** [`components/engine/engine-document/CLAUDE.md`](components/engine/engine-document/CLAUDE.md). Renderer v1 limits (documented, deliberate): header/footer render once in-flow (not repeated page regions), `repeatHeader`/`pageBreak` ignored, 1px = 1pt, a data-less table is skipped (FOP rejects empty table bodies).
-
-## Native applications (`engine-native-apps`)
-
-User projects can declare a `*.nativeapp` JSON file that turns an external web server — local OS process or remote HTTP(S) endpoint — into a first-class Dirigible artefact, reverse-proxied under `/services/native-apps-proxy/v1/<basePath>/...` with optional Dirigible-managed authentication and role-based access. The whole feature lives in `components/engine/engine-native-apps`.
-
-**Detailed guide:** [`components/engine/engine-native-apps/CLAUDE.md`](components/engine/engine-native-apps/CLAUDE.md). Read it before changing anything under that module — it covers the synchronizer model, kinds + start modes, port resolution, the stop / teardown contract (three layered guarantees), the dual-DELETE rehydrate requirement, PID + port logging, the proxy filter chain, placeholder expansion, the credentials field naming, the management endpoint's role policy, integration-test patterns including the no-manual-cleanup rule, and the macOS gotchas (Python 3.14 bind regression, wildcard-vs-loopback `ServerSocket` probe, `PollingWatchService` deadlock).
-
-## Tenant resolution strategy (`core-tenants` + `core-base`)
-
-How the current tenant of a request is determined is configurable through `DIRIGIBLE_TENANT_RESOLUTION_STRATEGY` (`TenantResolutionStrategy` in `core-base`, read once per `TenantExtractor` instance, i.e. at context refresh):
-
-- **`SUBDOMAIN`** (default, unchanged behaviour) — the subdomain of the `host` / `x-forwarded-host` header is matched against `DIRIGIBLE_TENANT_SUBDOMAIN_REGEX` and looked up by subdomain. A host naming no registered tenant is answered with the 404 written by `TenantContextInitFilter`. Every tenant needs its own host.
-- **`TOKEN_GROUPS`** — the tenant is the one the user selected, read from the HTTP session attribute `TenantSelectionConstants.SELECTED_TENANT_ID_SESSION_ATTRIBUTE` and required to be `PROVISIONED`. The host is never consulted, so one host serves every tenant. No session, no selection, an unknown selection, or a tenant that is not provisioned yet all fall back to the **default tenant** — machine-to-machine calls and anonymous requests carry no session, and a stale selection must not lock a user out.
-
-`TOKEN_GROUPS` exists for deployments where authorization is carried in identity provider groups named **`<tenantId>.<appId>.<role>`** (e.g. `acme.library.Owner`). `TenantGroupsParser` (`core-base`, `base/tenant/groups/`, free of Spring/servlet/OAuth2 types) turns a user's groups into `UserTenantAssignments`: groups of this deployment's application (`DIRIGIBLE_APP_ID`) become that tenant's roles, groups of other applications are ignored, and non-tenant-bearing groups (plain `DEVELOPER`, `OPERATOR`) stay global roles. The role part may contain dots; tenant and application ids may not. The groups claim is `DIRIGIBLE_TENANT_GROUPS_CLAIM` (`cognito:groups` by default, `groups` on Keycloak realms) — **set it explicitly on a Keycloak realm**: it is the one place both the login mapping and the selection read, so a wrong claim silently means "no tenants".
-
-## Tenant selection (`security-oauth2`, both OIDC profiles)
-
-What writes the session attribute — the identity-provider half of `TOKEN_GROUPS`. It lives in `security-oauth2` (`.../oauth2/tenant/`) rather than in a profile module, because Cognito and Keycloak need the same thing and their configurations differ only in the groups claim. Everything here is gated on the strategy, not on a Spring profile, so it is inert in `SUBDOMAIN` mode.
-
-- **`TenantAwareAuthoritiesMapper`** behind each profile's `userAuthoritiesMapper()`: in `SUBDOMAIN` mode every group of the provider's own claim becomes an authority (byte-identical to what the two profiles did inline before); in `TOKEN_GROUPS` mode only `globalRoles()`, since which tenant's roles apply is unknown at login.
-- **`TenantSelectionManager`**: `selectTenant` validates the tenant against the user's **own groups** (403 if not a member) and requires it `PROVISIONED` here (409), writes the session attribute and rebuilds the `OAuth2AuthenticationToken` with `globalRoles ∪ rolesFor(tenant)`, saved through the `SecurityContextRepository` — the `OAuth2SessionRevalidationFilter.refreshAuthentication` sequence, without rotating the session id. `ensureConsistent` re-applies them when they drift and **drops a selection whose group was revoked**.
-- **`TenantSelectionEndpoint`** at `services/security/tenant-selection`: `GET` lists `{selectedTenantId, tenants:[{id,name,provisionedHere}]}`, `POST {tenantId}` enters one and doubles as the switch. No `@RolesAllowed` on purpose — a user who has not picked yet has only global roles, and a single-tenant user none at all. JSON-only body is the CSRF defence (the chains disable CSRF tokens), as in `NativeLoginEndpoint`.
-- **`TenantSelectionFilter`**: one tenant → auto-select; several → `302 /tenant-selection.html` for a browser, `409 {"error":"TENANT_SELECTION_REQUIRED","tenants":[…]}` otherwise; none → pass for global-role holders, else 403. Non-`OAuth2AuthenticationToken` requests (M2M bearer, anonymous, basic) pass through.
-- **Registration** is `TenantSelectionSecurityConfigurator`, the repo's **first `CustomSecurityConfigurator`**. `HttpSecurityURIConfigurator.configure` applies those before its own matchers and every chain calls it, so one bean adds the filter `before AuthorizationFilter` (it must precede authorization, or a user without a tenant is 403'd before reaching the picker) and claims `/tenant-selection.html` as `authenticated()` — no per-profile wiring, no edit to the static URL matrix.
-- **The picker** is `security-oauth2/src/main/resources/static/tenant-selection.html` — Harmonia + Alpine, the load order of the Home landing page, inline script, `?switch=true` to change tenant. A classpath static page because the registry is itself tenant-scoped.
-
-⚠ In `TOKEN_GROUPS` mode the authorities of a session are **recomputed from the groups**, so a platform role such as `ADMINISTRATOR` must be granted as a *global group*; anything granted another way is dropped on the next request. Note also that a fresh selection applies from the **next** request: the tenant scope of the current one was opened before the selection was written, which is why the picker navigates away on success.
-
-`TenantResolutionConfigValidator` (`core-tenants`) refuses to start on an unusable combination: with `TOKEN_GROUPS` the app id must be set and dot-free, `DIRIGIBLE_MULTI_TENANT_MODE` must be true, the groups claim non-blank, and `DIRIGIBLE_MULTI_TENANT_MODE_COGNITO_SINGLE_USER_POOL` (the legacy `custom:tenant` model of `CognitoTenantFilter` / `KeycloakTenantFilter`, which resolve by subdomain and stand down under `TOKEN_GROUPS`) must be off. It validates **in its constructor** on purpose — a half-usable resolution setup must abort the context refresh rather than serve requests that silently land in the wrong tenant.
-
-Caches: `TenantExtractor.TENANT_CACHE` (by subdomain) and `TENANT_ID_CACHE` (provisioned tenants by id), both 10 min. Use `TenantExtractor.evictFromCaches(tenantId, subdomain)` after changing a tenant's registration or status; `TenantService.save/delete` already do.
-
-## Tenant-aware configuration (`commons-config` + `core-configurations`)
-
-Each tenant can override selected configuration values; overrides are resolved **per request**, scoped to the current tenant. Added on PR [#6205](https://github.com/eclipse-dirigible/dirigible/pull/6205).
-
-**Resolution precedence** (in `Configuration.get`): `RUNTIME (set() programmatic) → tenant thread map → ENVIRONMENT (env + sys props) → DEPLOYMENT (.properties) → MODULE`. The tenant map sits between the runtime variables and the environment, so a tenant override beats env/properties but a programmatic `Configuration.set` still wins.
-
-**Layering is load-bearing — do not break it.** `modules/commons/commons-config` sits at the bottom of the dependency graph and must stay dependency-free. It carries **only** the neutral mechanism: a `ThreadLocal<Map<String,String>>` in `Configuration` with `setThreadConfiguration` / `removeThreadConfiguration` / `getThreadConfiguration`, plus the `get()` precedence branch. It has **no** knowledge of tenants, DB, or where the values come from. Everything tenant/DB/policy-related lives one layer up in `components/core/core-configurations` (which depends on `data-sources`; `TenantContext` comes from `core-base`). Never add a tenant/DB dependency to `commons-config`.
-
-- **Store** (`tenant/TenantConfigurationStore`) — raw `SqlFactory` CRUD against `DataSourcesManager.getDefaultDataSource()`, which inside a tenant scope is auto-routed to that tenant's schema, so a distinct **`DIRIGIBLE_CONFIGURATIONS`** table (columns `CONFIGURATION_KEY` / `CONFIGURATION_VALUE`) lives per tenant schema; created create-if-absent on first use.
-- **Cache** (`tenant/TenantConfigurationCache`) — per-tenant map, loaded on first access, invalidated on write. Per-node only; a multi-node cluster would need an external invalidation signal (documented as out of scope).
-- **Key policy** (`tenant/TenantConfigurationKeyPolicy`) — an **explicit white-list of full keys (exact match, NO wildcards)**; default-deny for everything else, so a tenant can never shadow infrastructure keys. Allowed: the **branding** keys (`DIRIGIBLE_BRANDING_{NAME,SUBTITLE,BRAND,BRAND_URL,FAVICON,THEME,PREFIX,ANALYTICS}`) and `DIRIGIBLE_APPLICATION_LANGUAGES` (the per-tenant language set, default `en`). To widen, add concrete keys to `ALLOWED_KEYS` — do not reintroduce prefix/wildcard matching (that was explicitly rejected) and do not reintroduce a configurable `DIRIGIBLE_TENANT_CONFIGURATION_ALLOWED_KEYS` (removed). A non-allow-listed key can still be *stored* but is never injected.
-- **Request wiring** (`tenant/TenantConfigurationInitFilter`, `@Order(LOWEST_PRECEDENCE)`) — runs downstream of the Spring Security filter chain, i.e. **inside** the tenant execution scope established by `core-tenants`' `TenantContextInitFilter`; it loads the allow-listed entries into the thread map for the request and clears them in `finally`. **Do not move this into `TenantContextInitFilter`** — that would force `core-tenants` to depend on `core-configurations` (cycle). Keep it in `core-configurations`.
-- **REST** (`endpoint/TenantConfigurationsEndpoint`, `ADMINISTRATOR`/`OPERATOR`) at `services/core/configurations/tenant`: `GET` (stored entries), `GET /predefined` (every allowed key with the tenant's value or `null`), `PUT` `{key,value}`, `DELETE ?key=`.
-- **UI**: a built-in **Tenant Configuration** entry in the Harmonia **application shell** Settings (`components/resources/resources-application` — `views/_settings.html` + `js/appShell.js`), rendered locally like Region & Language: lists the predefined branding props with editable values (empty → platform default), Save/Reload, 403 → permission notice. A generic AngularJS CRUD view also exists in `components/ui/view-configurations` (`tenant-configurations.html`) for arbitrary keys.
-
-**Making a new property tenant-overridable (the whole recipe):**
-
-1. **Add the exact key** to `ALLOWED_KEYS` in `components/core/core-configurations/.../tenant/TenantConfigurationKeyPolicy.java` — a full key string, e.g. `"DIRIGIBLE_THEME_DEFAULT"`. No prefixes, no wildcards. This single edit is all that is functionally required: the key becomes injectable, is returned by `GET /services/core/configurations/tenant/predefined`, and **appears automatically** in the Harmonia Settings "Tenant Configuration" page (the page is data-driven from `/predefined`) and in the REST/AngularJS management surfaces.
-2. **Read it at request time.** The override only takes effect for code that calls `Configuration.get("<KEY>")` (or `DirigibleConfig.<X>.getStringValue()`) **during a request, inside the tenant scope**. A value read once at boot or cached in a bean/`static` field will not reflect per-tenant overrides — read it lazily per use. (Branding already works because the branding services read it live.)
-3. **Label (optional).** The Settings page derives a display label in `appShell.js` `tenantConfigLabel()`, which strips the `DIRIGIBLE_BRANDING_` prefix. For a non-branding namespace, extend that helper so the label reads nicely; otherwise it falls back to a de-prefixed, title-cased form of the key.
-4. **Tests.** Add the key to `TenantConfigurationKeyPolicyTest` (allowed set) and, if you want end-to-end coverage, mirror `TenantConfigurationIT` (set → resolve with precedence → clear).
-
-Do **not** widen by reintroducing wildcards or a config-driven allow-list — the explicit in-code white-list is deliberate (a tenant must never be able to shadow infrastructure keys).
-
-**SqlFactory quoting gotchas (bit this feature twice):** the `create().table()` builder takes **pre-quoted** identifiers (the `TableCreateProcessor` pattern), while `select/insert/update/delete` and the `where(...)` condition **auto-quote** — pass **unquoted** names there. A VARCHAR length arg must include its own parens: `column(..., "(255)")`, not `"255"` (renders `VARCHAR (255)`).
-
-## Conventions worth knowing
-
-- **Always write production-ready Java.** Every change must be production-grade and follow accepted Java best practices and clean-code principles — never prototype-quality, throwaway, or "good enough for now" code. This means: clear intention-revealing names; small, single-responsibility methods and classes; correct visibility and immutability (prefer `final`, avoid leaking mutable state); proper resource handling (try-with-resources); precise exception handling (no swallowed exceptions, no catch-and-ignore, fail at the right boundary); no dead code, no unused parameters/fields, no commented-out blocks; thread-safety where the runtime demands it; and defensive validation only at real system boundaries (trust internal invariants — see the global guidance against over-engineering). Favour the simplest correct design over cleverness, and keep behaviour and naming consistent with the surrounding module. Apply this standard by default to all Java in this repo without being reminded.
-- **Constructor injection only.** Every Spring bean (`@Component` / `@Service` / `@Repository` / `@Configuration` / `@RestController` / synchronizer / filter / scheduler) receives its collaborators through the constructor and holds them in `private final` fields. No `@Autowired` (or `@Inject`) on fields, no setter injection. With a single constructor, omit the redundant `@Autowired` on it. `AuthenticationInjectorRegistry` in `engine-native-apps/auth/` is the canonical example — list-typed multi-bean intake plus an immutable derived map, all in the constructor. **Documented exception:** Quartz `Job` implementations. `AutoWiringSpringBeanJobFactory.createJobInstance` instantiates jobs via `clazz.getDeclaredConstructor().newInstance()` and then calls `AutowireCapableBeanFactory.autowireBean(job)`, which only handles property/field/setter autowiring — never constructor args. `JobHandler`, the `DirigibleJob` hierarchy, and `NativeAppMonitorJob` keep `@Autowired` on collaborator fields and document the Quartz instantiation contract in a class-level comment. Do the same when adding a new Quartz Job; don't try to rewire the factory.
-- **Package-private by default.** Drop the `public` modifier from any class, interface, or enum used only within its own Java package — including its constructors and methods where the smaller surface is reachable. Cross-package use within the same Maven module still requires `public` (Java packages don't nest, so `org.eclipse.dirigible.x.auth` cannot see a package-private type from `org.eclipse.dirigible.x.proxy`). The SPI types other packages or modules extend stay `public`; the Spring-internal `@Component`s wired by other beans in the same package, helper classes, filter implementations referenced only by their router config, and DTOs consumed only by their endpoint become package-private. `engine-native-apps/proxy/*` is wholly package-private; `engine-native-apps/auth/` keeps the `AuthenticationInjector` SPI public but demotes `BasicAuthenticationInjector`. **Documented exceptions:** Quartz `Job` classes (Quartz's `Constructor.newInstance` call from `org.quartz.*` fails the language-access check on a package-private class) and Spring Data JPA repositories (Spring Data scans classpath-wide; package-private is brittle in practice).
-- **Never print to stdout or stderr - log.** No `System.out.println`, no `System.err.println`, no bare `e.printStackTrace()` anywhere in platform code. A print is invisible to the Logs view and to log aggregation, carries no level, timestamp, logger name or thread, cannot be turned down in production, and pollutes the console stream the IDE terminal shows. Use the module's SLF4J `private static final Logger LOGGER = LoggerFactory.getLogger(X.class)` at the level the event deserves (`debug` for tool output like a bundler's own lines, `warn` for a recoverable data problem, `error` **with the throwable** for a failure). In **generated / scaffolded client code** (the `template-application-*` templates, the `custom/` stubs the intent engine scaffolds) use the client SDK logger instead - `Logging.getLogger("gen.events.<module>.<Class>")` from `org.eclipse.dirigible.sdk.log` - which nests under the platform's `app.` root and shares its configuration; a generated class that prints teaches every application developer to do the same. **The one documented exception** is `ConsoleWebsocketHandler.distribute`, which is called *by* the logging appender: logging there re-enters the appender and recurses, so `System.err` is correct in that single method and the comment there says so. When in doubt, grep before you commit: `grep -rn "System\.\(out\|err\)\.print\|printStackTrace()" --include="*.java" --include="*.template" components modules | grep -v /target/ | grep -v /src/test/`.
-- **Always log the throwable.** Every `catch` block's log call must pass the exception as the trailing SLF4J argument so the stack trace lands in the log — at every level, including DEBUG. Never log only `ex.getMessage()` and drop the rest. SLF4J's parameterised form `logger.X(format, …, throwable)` treats the trailing throwable as out-of-band; the `{}` placeholder count vs. format-arg count stays balanced. Even for cases where the exception "feels expected" (an `IOException` in a daemon log pump that just means the child closed its pipe), keep the throwable so an operator who bumps the level can investigate. Skip the throwable only when there is genuinely no exception in scope (validation failures detected via `if`, not `try`).
-- **Code formatting is enforced — always run `mvn formatter:format` before every commit and push.** This is mandatory: the `code-style` CI job (`.github/workflows/build.yml`) runs `mvn formatter:validate` and fails the build on any violation, so unformatted code will not merge. Run `mvn formatter:format` (scoped to the changed module with `-pl` for speed) as the final step before staging, every time. The IDE setup (Eclipse / IntelliJ / VS Code) for importing `dirigible-formatter.xml` is documented in `CONTRIBUTING.md`.
-- **Javadoc has to compile cleanly on every Maven module that participates in the release** (anything under `components/`, `modules/`, `dependencies/`, `build/`, `tests/tests-framework`, `cli/`). The release profile attaches the `maven-javadoc-plugin:jar` execution and treats any `error:` from javadoc as fatal; the `default` profile silently skips javadoc, so problems are invisible in normal `mvn install` and only surface in `.github/workflows/release.yml`. **Run `mvn -P release -Dgpg.skip=true -DskipTests -Dlicense.skip=true -Dformatter.skip=true install` on the modules you've touched before pushing anything that adds or changes javadoc.** The recurring failure modes:
-  - **Malformed HTML from a bare `<`.** Javadoc prose is HTML — doclint parses any bare `<` as a tag start, including inside `<pre>` blocks. ASCII arrows are the classic trap: `# child field <- literal` in a `<pre>` YAML example fails as `error: malformed HTML` (broke the 2026-07-10 release via `ExpansionIntent.java`). Escape as `&lt;` (`&lt;-`), or wrap the whole example in `<pre>{@code ... }</pre>` so nothing inside is HTML-parsed. Same for `>`/`&` when ambiguous.
-  - **Unterminated inline tag.** `{@code` / `{@link` parse braces inside their argument as inline-tag delimiters. `{@code {{ }}}` — the inner `{{` opens a phantom tag and javadoc can't find the matching `}` until the next paragraph break. Escape with `<code>&#123;&#123; &#125;&#125;</code>` or rephrase to avoid braces inside braces.
-  - **`@link` reference not found.** `{@link some.external.Type}` only resolves when that type is on the javadoc tool's classpath. JUnit Jupiter, Lombok, optional-test deps and friends are typically not. Use `{@code some.external.Type}` (plain text formatting, no resolution) when the reference is purely documentation; keep `{@link …}` only for types this module compiles against.
-  - **`no comment` warning.** Add a one-liner Javadoc to every `public` member of an exported SDK class — javadoc 17+ promotes these to errors under `-Xdoclint:all`, and even today they look untidy in the published API docs.
-  Default to writing concise Javadoc on every `public` SDK / API class and method (one sentence is fine), since these are the surfaces user projects link against and the only ones whose docs get published. Internal Spring beans, IDE plumbing, and tests don't need it — comments on intent over comments on shape, per the global rule.
-- **License headers are checked.** Every Java/JS/properties file carries the EPL-2.0 header. New files should include it; `mvn license:format -P license` will add or refresh it. Most local-iteration profiles set `license.skip=true`, but the default `mvn install` does not.
-- **Integration tests boot the full Spring app and drive Chrome via Selenide.** Pass `-D selenide.headless=true` to run them on CI/headless machines. Screenshots end up in `tests/tests-integrations/build/reports/tests`.
-- **UI module resources are bundled into the `build/application` fat jar — a running instance does NOT hot-reload them.** After editing anything under `components/ui/*` or other `META-INF/dirigible/**` web resources, you must `mvn -P quick-build install -pl <module>` **and** `mvn -P quick-build package -pl build/application`, then restart `java -jar build/application/target/...jar`, before a locally running instance reflects the change. Integration tests repackage `tests-integrations` independently, so a **green IT never proves the user's running jar is current** — when a user reports "nothing changed," verify the served resource first (e.g. `curl -s -u admin:admin http://localhost:8080/services/web/<module>/...js | grep <new-token>`).
-- **DB-specific behavior is covered by parametrized CI.** `build.yml` runs the integration suite twice — H2 (default) and PostgreSQL 16 — by varying the `DIRIGIBLE_DATASOURCE_DEFAULT_*` env vars. When touching SQL or schema-emission code, replicate this locally for the affected DB rather than assuming H2 behavior generalizes. MSSQL is **no longer in CI** (removed in #6150): the SQL Server dialect + driver still ship and work for opt-in customers, but they own the `IDENTITY`/`IDENTITY_INSERT` trade-off (MSSQL uniquely rejects explicit-ID inserts into `IDENTITY` columns, which conflicts with the generated Java entity's `@GeneratedValue(IDENTITY)` path — `TableCreateProcessor` emits a plain `INT` on MSSQL). Don't assume MSSQL is exercised by any test.
-- **WebJars / `dirigiblelabs` modules.** Some IDE-side modules (names starting with `ide-`, `api-`, `ext-`) historically lived as separate repos under [dirigiblelabs](https://github.com/dirigiblelabs); per `CONTRIBUTING.md` step 8 you may need `mvn clean install -Pcontent` to pull their latest content if working across them.
-- **`*IT.java` vs `*Test.java` matters** — failsafe picks up the former, surefire the latter. Putting an integration test under a `*Test` name will silently run it during the wrong phase (and likely without the test app context).
-- **Configuration goes through `DirigibleConfig` / `Configuration`** (`modules/commons/commons-config`). When introducing a new tunable, add the enum entry there with a `DIRIGIBLE_*` env-var key and a sensible default — don't read env vars or `System.getProperty` ad-hoc.
-- **Spring beans glue everything together; `StaticObjects` is legacy.** Some code paths still grab dependencies via `StaticObjects.get(...)` (e.g. `RepositoryConfig` registers `IRepository` there explicitly) because parts of the runtime predate Spring. New code should rely on constructor injection; don't add new `StaticObjects` keys.
-- **Bean-definition overriding is enabled** (`spring.main.allow-bean-definition-overriding=true` in `application-common.properties`), so a duplicate `@Bean` name will silently shadow another. Be deliberate about bean names.
-- **JPA scan packages are `{ "org.eclipse.dirigible.components", "org.eclipse.dirigible.engine" }`** in `DataSourceSystemConfig` (both `@EnableJpaRepositories(basePackages = …)` and the `dirigible.scan.packages` property default). New artefact-bearing modules under either tree are picked up automatically; modules under other roots won't be.
-- **Cross-module FK cascades use `@OnDelete(action = OnDeleteAction.CASCADE)`.** `core-tenants` depends on `engine-security` (for `Role`), not the reverse, so a JPA-level bidirectional cascade from `Role → UserRoleAssignment` would form a module cycle. `UserRoleAssignment.role` instead carries `@org.hibernate.annotations.OnDelete(action = OnDeleteAction.CASCADE)`, which makes Hibernate emit `ON DELETE CASCADE` on the FK at schema-generation time and the DB drops the assignment row when its role is deleted. Without this, removing a `.roles` artefact whose role was still assigned to a user tripped `FK… DIRIGIBLE_USER_ROLE_ASSIGNMENTS → DIRIGIBLE_SECURITY_ROLES` and the role row survived in the DB out of sync with its missing source file. `RoleSynchronizerCleanupIT` covers it end-to-end. **Caveat for migrations:** Hibernate only emits the cascade when the FK is *created*; existing deployments keep the old un-cascading constraint until the table is rebuilt. Apply the same pattern for any new artefact-bearing entity that owns an FK to a synchronizer-managed parent.
-- **Spring Boot 3 fat-jar classpath is fragile.** Reading `BOOT-INF/lib/*.jar` resources via `ClassLoader.getResourceAsStream` — or via aggressive scanners like ClassGraph — closes pooled `NestedJarFile` handles inside `LaunchedClassLoader` and causes cascading `NoClassDefFoundError`s in unrelated platform code. If you need the platform classpath (e.g. as input to `javac --class-path`), follow `engine-java.runtime.ClassPathIndex`: open the outer fat jar with the standard `java.util.jar.JarFile`, extract `BOOT-INF/lib/*.jar` + `BOOT-INF/classes/` to a temp dir once, and use those on-disk paths. Don't introspect nested jars in-process.
-- **HTTP-driven integration tests are an option.** Most existing ITs extend `UserInterfaceIntegrationTest` and drive the IDE via Selenide — heavy and slow. For a feature you can exercise purely over HTTP, extend `IntegrationTest` instead, write fixture files directly through `IRepository.createResource(...)`, call `SynchronizationProcessor.forceProcessSynchronizers()` to trigger reconciliation synchronously, and assert via `RestAssuredExecutor.execute(callable, timeoutSeconds)` (the retry-on-AssertionError overload absorbs the small async gap between sync-return and dispatch). See `JavaEngineIT` for the pattern; it runs headless without Chrome. When the fixture is a whole project under `src/main/resources/<Name>/`, `ProjectDeployer` (tests-framework) is the shortcut: `deploy(folder)` copies it into the default user's workspace and calls the same publish endpoint the IDE's Publish button calls, `deployGeneratedFromModel(folder, "edm.model")` first calls the generation endpoint the entity modeler's Regenerate calls (reading the project's own `.gen` for the template and parameters, minus the six keys the modeler sends as request fields), and both then run the synchronizers to completion — the camel route ITs are the family that moved off Chrome this way. **Attach a `LogsAsserter` in `@BeforeEach`, never in a field initializer:** Spring re-initializes logback while it starts the application context — after the test instance is constructed — and that reset drops an appender attached any earlier, so the assertion times out against a message the log plainly shows. `forceProcessSynchronizers()` is reliable since the engine-intent PR: it used to silently no-op when the scheduled `SynchronizationJob` was mid-run (the root cause of `LocalNativeAppLifecycleIT`-style flakes); it now retries until a full pass has actually consumed the force flag (bounded at 5 minutes).
-- **Synchronizer artefact locations are registry-relative; `IRepository` paths are repository-absolute.** `SynchronizationWalker` strips the registry folder, so an artefact's `location` looks like `/myproject/file.ext` — but to read or write that file through `IRepository` you must prepend `IRepositoryStructure.PATH_REGISTRY_PUBLIC`. Code that confuses the two writes outside `/registry/public`, where no synchronizer, IT assertion, or Registry view will ever see the output (engine-intent shipped this bug once — see its CLAUDE.md "wrong turns"). The same convention shows up in `SynchronizationProcessor`'s cleanup pass and `CsvimProcessor.getCsvResource`.
-- **`JsonHelper`/`GsonHelper` exclude fields without `@Expose` — and pretty-print.** Their Gson is built with `excludeFieldsWithoutExposeAnnotation()`, so `fromJson` into a POJO whose fields lack `@Expose` silently produces an all-null object (no exception — engine-intent's parser "worked" while generating nothing). Map-shaped data is unaffected (maps aren't field-reflected). For POJO mapping either annotate every field or use a private plain `Gson`; when asserting generated JSON content in tests remember the output is pretty-printed (`"key": "value"` with a space).
-- **Windows CI fails any test that leaves a file handle open under a JUnit `@TempDir`.** POSIX deletes open files; Windows refuses, and JUnit's temp-dir cleanup turns that into "JUnit Failed to close extension context" — only on the `tests (windows)` leg, never locally on macOS/Linux. Two real burns, both in the dynamic-dependencies work: a test swapped a jar into `ModulesClassLoaderHolder` (holders deliberately never close loaders — the TEST must close the swapped `URLClassLoader` in `finally`), and a mocked `Instrumentation` captured the real `JarFile` passed to `appendToSystemClassLoaderSearch` (production keeps it open for the process lifetime by design — the test closes the captured instances in `@AfterEach` via Mockito `ArgumentCaptor`). Rule: whatever `JarFile`/`URLClassLoader`/stream a test causes to open on fixture files under `@TempDir`, the test itself must close, even when the production code's contract is to keep it open.
-- **Stale H2 files break IT runs after a killed JVM.** The file-backed H2 under `tests/tests-integrations/target/dirigible` survives a killed test run and the next context fails to load with `missing artefact with name: [DefaultDB]` or `Table ... not found (this database is empty)` cascades. `rm -rf tests/tests-integrations/target/dirigible` before re-running locally.
-- **Sample-project tests live in `tests/ui/tests/sample/` and come in FAMILIES, not one class per sample.** `SampleProjectsIT` clones a *list* of `dirigiblelabs/*` repos through the IDE Git perspective, calls `Workbench.publishAll(true)` once, runs `forceProcessSynchronizers()` + `waitForStableSynchronization()`, and does all of that once under `@DirtiesContext(AFTER_CLASS)`; each subclass then verifies one sample per `@Test`. The clone-and-publish runs in a **`@BeforeEach` guarded by the family class**, deliberately not in a `@BeforeAll` on a `@TestInstance(PER_CLASS)` class — PER_CLASS autowires the test instance *before* `@BeforeAll`, so the platform boots before `IntegrationTest.cleanBeforeTestClassExecution()` deletes the Dirigible folder and the next sync pass reaps the platform's own registry (it surfaces as "`perspective-git` not found" on a blank page, nowhere near the cause). UI-based (Selenide → Chrome), slower than HTTP-only ITs — which is exactly why the boot, the browser and the publish cycle are shared. Three subclasses: `TypeScriptSampleProjectsIT` (the TS/JS decorator samples), `JavaSampleProjectsIT` (the client-Java samples) and `SampleLibraryLocalNativeAppIT` (alone, because it spawns a real OS process). **The family split is a runtime constraint, not taste:** `sample-entity-decorators` and `sample-java-entity-decorators` both own the `SAMPLE_COUNTRY` table and both CSVIM-seed it, so they cannot be published into the same instance. Before adding a sample to a family, check it against the family for a table/route/queue/websocket-endpoint/Java-FQN collision (the whole family shares one `javac` batch and one `ClientClassLoader`), and keep the verification order-independent — the methods run against one live instance. When adding a new sample, drop the project in its own `dirigiblelabs/*` repo first, then add its URL to a family's `getRepositoryUrls()`. Inventory of sample repos under `dirigiblelabs/*`: `sample-entity-decorators`, `sample-java-entity-decorators`, `sample-roles-decorator`, `sample-job-decorator`, `sample-listener-decorator`, `sample-extension-decorator`, `sample-component-decorator`, `sample-websocket-decorator`, `sample-store-api`, `sample-intent-model`. `IntentEditorLoadsIT` is not a `SampleProjectsIT` subclass (the intent generates in the workspace, not on publish) but uses the same clone-a-real-repo pattern: it clones `dirigiblelabs/sample-intent-model`, opens its `app.intent`, and drives the editor's Generate.
-- **Spring Boot 4 strips `ResponseStatusException.getReason()`** from the default JSON error body even with `server.error.include-message=always` in `application-common.properties`. Status code reaches the client correctly; the reason text doesn't. ITs asserting 404 must check `statusCode` only, not body content (`JavaEngineIT.delete_unregisters_handler` and `compile_error_keeps_endpoint_unregistered` learned this the hard way — see commit `f13c8c219e`).
-- **The client-Java effort is split across three repositories.** The platform code (engine-java, data-store-java, IT) ships in this repo via PR [#5923](https://github.com/eclipse-dirigible/dirigible/pull/5923). The sample project that `JavaSampleProjectsIT` clones lives in [`dirigiblelabs/sample-java-entity-decorators`](https://github.com/dirigiblelabs/sample-java-entity-decorators) (initial content from PR [#1](https://github.com/dirigiblelabs/sample-java-entity-decorators/pull/1)). The announcement blog "Return of the Java – Decorators Awaken in Eclipse Dirigible" (sister piece to the December 2025 TS decorators post) goes through the docs portal in PR [`dirigible-io/dirigible-io.github.io#123`](https://github.com/dirigible-io/dirigible-io.github.io/pull/123). Follow-up Java-runtime features generally touch the same three places.
-
-## Browser UI — BlimpKit gotchas
-
-The IDE shell and most editor perspectives render through **BlimpKit**, a thin AngularJS-on-Fundamental-Styles component library that lives in `components/ui/platform-core/src/main/resources/META-INF/dirigible/platform-core/ui/blimpkit/` (Angular module name **`blimpKit`** — camelCase, declared in `blimpkit.js`). The runnable artifact is the bundled `/webjars/blimpkit__blimpkit/dist/blimpkit.min.js` (~158 KB, currently webjar 2.1.6). Findings below are the ones that have already burned someone — read once, save hours later.
-
-- **`<bk-checkbox>` is invisible without `<bk-checkbox-label>`.** `bk-checkbox` compiles to a bare `<input type="checkbox" class="fd-checkbox">`. Fundamental-Styles' `.fd-checkbox` rule hides the native input (`opacity:0; position:absolute`) on the assumption that a sibling `<bk-checkbox-label>` will draw the visible square via its `.fd-checkbox__checkmark` ::before pseudo. A lone `<bk-checkbox>` is therefore a working click target with zero visible chrome — easy to ship and never catch in code review. Pair it: `<bk-checkbox id="x" ng-model="…">` followed by `<bk-checkbox-label for="x" empty="true">…</bk-checkbox-label>` (the `empty="true"` attribute drops the inner text container so the label provides just the checkmark — use it when the surrounding markup already labels the row).
-- **`<bk-dialog>` has an isolate scope.** You can't put `ng-controller="…PopupCtrl"` on the dialog element itself — Angular throws "Multiple directives [bkDialog, ngController] asking for new/isolated scope on: <bk-dialog>". Wrap with a thin `<div ng-controller="…">` and put `<bk-dialog visible="…">` inside.
-- **`<bk-select>` doesn't support `ng-options`.** Use `<bk-option ng-repeat>` instead — text via the `text` attribute, model value via `value`. Example: `<bk-option ng-repeat="opt in items" text="{{opt.name}}" value="opt.id">`. When the select sits in a parent with `overflow:hidden` (a dialog, a sidebar), add `dropdown-fixed="true"` so the menu floats via `position:fixed` instead of being clipped.
-- **`<bk-option>`'s `text` and `value` bind differently** — `text: '@'` is **interpolation** (use `text="{{ expr }}"` or a literal), `value: '<'` is a **one-way expression** (use `value="expr"`, never `value="{{ expr }}"`). Mixing them up is the canonical bug for this directive:
-  - `value="{{s}}"` makes Angular try to parse `{{s}}` as a JS expression, the directive's link silently fails, and the dropdown shows raw `{{ text }}` from the unlinked template (one ghost item per ng-repeat iteration, not six). Fix: `value="s"`.
-  - `value="user"` evaluates `$scope.user`, not the string `"user"` — every option ends up with the same `undefined` value and selection becomes a no-op. For string literals, quote inside: `value="'user'"`. For the empty default option, `value="''"`, not `value=""` (which is the undefined-expression).
-  - Numeric literals (`value="2"`) and loop variables (`value="s"`) are already expressions — leave them unquoted. Numbers stay numbers, so `selectedValue === '2'` will fail; either store as numbers on the model or coerce in the controller (the refresh-interval dropdowns in `view-jvm-monitoring` / `view-jvm-threads` `parseInt` the model on read).
-- **Perspective SVG icons inherit `fill` from CSS — don't hard-code `fill` on the path.** `blimpkit.css` styles `.fd-list__navigation-item i.bk-icon--svg svg` with `fill: var(--fdVerticalNav_Icon_Color, #303030)` (and `var(--sapSelectedColor)` on the active state). The CSS only takes effect on `<path>` elements with **no own `fill`** — adding `fill="#000000"` (the default when you paste an SVG from a web icon set) locks the icon to black and breaks dark-theme adaptability. Strip the fill attribute (jobs.svg / operations.svg pattern) or set `fill="currentColor"` (database.svg pattern). The container svg's other niceties (`width="512"` / `height="512"` / `stroke-width=".99999"`) don't affect rendering through this CSS but are the established style.
-- **`<bk-input>` / `<bk-textarea>` / `<bk-button>` use `replace:true`.** The attributes you write on the directive element (ng-model, ng-blur, ng-keypress, ng-disabled, custom directives like `auto-focus` / `select-text`) end up on the underlying native `<input>` / `<textarea>` / `<button>`, so existing controller code keeps working unchanged after migrating native form controls to `bk-*`. ng-model binds against the parent scope — the isolate scope `bk-input` declares only owns `compact` / `state` / `glyph`.
-- **Don't put `ng-class` on a `replace:true` directive element that already has its own `ng-class`.** `bk-table-header-cell`, `bk-table-cell`, and most layout-y BlimpKit directives template as `<th ng-class="getClasses()" …>` — Angular's attribute merge **string-concatenates** duplicate `ng-class` values, producing nonsense like `ng-class="{ sorted: sort.key === 'id' } getClasses()"`. The page then throws `$parse:syntax` at compile time and the row never renders. (`class` merges cleanly — only `ng-class` is broken — so `class="no-sort"` on a `<th bk-table-header-cell>` works fine.) The fix: push the conditional class onto a child element instead of the directive root: `<th bk-table-header-cell ng-click="…"><span class="sort-caret" ng-class="{ active: sort.key === 'id' }">{{ caret() }}</span></th>`. Same applies for anything else with a `replace:true` + `ng-class` template (audit `components/ui/platform-core/.../blimpkit/*.js` for the pattern before adding `ng-class` to a `bk-*` directive).
-- **The `blimpKit` module's `.config()` block disables three `$compileProvider` flags.** `cssClassDirectivesEnabled(false)`, `commentDirectivesEnabled(false)`, and `debugInfoEnabled(false)` are flipped at module-load when debug info was on — saves per-element scope-tracking overhead in production. The last flag breaks Selenide-style debugging that calls `angular.element(node).scope()`: Angular stops attaching scope refs to DOM nodes, so the lookup returns `undefined`. If your app or its integration tests rely on that, re-enable the flags in a `.config(['$compileProvider', …])` block of your own — module config blocks run in dependency order, so `blimpKit`'s flips happen first and your override sticks.
-- **SAP-icons + the "72" body font live in platform-core's `fonts.css`.** Every BlimpKit-using page needs `<link rel="stylesheet" href="/services/web/platform-core/ui/styles/fonts.css">`. Without it `.sap-icon--*` glyphs render as tofu squares because the `@font-face { font-family: "SAP-icons"; … }` declaration is missing. The IDE shell loads this automatically via the `platform-links` injection mechanism (see below); standalone iframes (editor-bpm, embedded views) have to add the link tag explicitly. Other `@font-face` rules in the same file declare the body font: `"72"` (Regular / Light / Bold), `"72-Light"`, `"72-Bold"`, `"72Mono-Regular"`, `"72Mono-Bold"`, plus `"BusinessSuiteInAppSymbols"` and `"SAP-icons-TNT"`.
-- **`<meta name="platform-links" category="…">` auto-injects scripts + stylesheets.** Looking at any non-iframe perspective HTML you'll see a single `<meta name="platform-links" category="ng-view,ng-perspective">`-style tag in the `<head>`. `HtmlPlatformLinksInjector` (in `components/engine/engine-web/.../HtmlPlatformLinksInjector.java`) reads it at request time, walks the `category` list, and replaces the meta tag with the bundle of `<link>` and `<script>` tags registered for those categories. Categories are defined in `components/engine/engine-web/src/main/resources/platform-links.json` — `ng-view` is the heavyweight bundle (jQuery, AngularJS, all the platform hubs, BlimpKit, Fundamental-Styles, fonts.css), `ng-perspective` adds split + layout, `ng-editor` adds workspace + repository hubs, etc. Adding new shared platform code → add it to this JSON, not to every perspective HTML.
-- **`<bk-dialog>` toggles visibility via the `visible` binding, not a `.modal('show')` plugin.** `<bk-dialog visible="modal.visible">` watches the expression and adds `fd-dialog--active` when true. No backdrop element is added (the dialog's own `.fd-dialog--active` overlay handles z-index + dimming). To dismiss programmatically: flip the bound flag (`scope.modal.visible = false`) inside an `$apply`; let the directive's digest cycle remove the `--active` class; then `$timeout` ~300ms later before tearing down the scope so the close animation completes.
-- **Test selectors after a BlimpKit migration.** Native `<input class="form-control">` → `<input class="fd-input fd-input--compact">`. `<div class="modal in">` (Bootstrap-3 visible) → `<section class="fd-dialog fd-dialog--active">`. `body.modal-open` and `.modal-backdrop` are NOT set by `<bk-dialog>` — drop assertions on those, the active overlay handles its own dimming. When fixing Selenide tests that look at `.modal-header .close`, switch to `.fd-dialog__header .fd-button` (or scope to the dialog with `section.fd-dialog--active button.fd-button`).
-- **A `<split>` splitter needs the `platformSplit` module in the app's dependency list — loading the script is not enough.** The `<split>`/`<split-pane>` resizable-pane directives are defined in Angular module `platformSplit` (`platform-core/ui/platform/split.js`). The script + `split.css` are already bundled by the `ng-perspective` (and `ng-split`) `platform-links` categories, so a perspective that declares `ng-perspective` does NOT also need `ng-split`. But every app must still list `'platformSplit'` in its `angular.module('app', [...])` deps, or the directives never register: `<split>`/`<split-pane>` stay inert unknown elements and the layout collapses (one pane fills everything, the others vanish — with no console error). Working examples: `editor-csvim`, `perspective-settings`, `resources-inbox`. Layout: `.bk-split` is `height:100%`, so under a persistent `<bk-toolbar>` in a `bk-vbox` body wrap the split in `<div class="bk-stretch">` (see `resources-documents`); wrap each pane's content in `<div class="bk-vbox bk-fill-parent">`; `split-pane size` values should sum to 100; the gutter replaces any manual `bk-border--*`.
-
-## Java Debugger (`ide-java-debug` + `view-java-debug`)
-
-Implemented in PR [#5948](https://github.com/eclipse-dirigible/dirigible/pull/5948). Bridges the browser IDE to a JDWP-enabled JVM via the Debug Adapter Protocol (DAP).
-
-### Architecture
-
-```
-Browser (debug.js) ←WebSocket→ JavaDebugWebSocketHandler
-                                  ↓ JavaDebugManager
-                                  ↓ JavaDebugBridge (per workspace)
-                                  ↓ DAP TCP socket
-                                  JDT.LS (vscode.java.startDebugSession)
-                                  ↓ JDWP TCP (port 8000 by default)
-                                  Target JVM
-```
-
-**Key classes:**
-- `JavaDebugManager` (`components/ide/ide-java-debug`) — singleton Spring bean; one `JavaDebugBridge` per `username/workspace` key. `getOrStart()` is the entry point: asks JDT.LS for a DAP TCP port via `workspace/executeCommand → vscode.java.startDebugSession`, then creates the bridge. `removeSession()` tears down the bridge when the last WebSocket session leaves.
-- `JavaDebugBridge` — reads Content-Length-framed DAP messages from the TCP socket and broadcasts them as raw JSON to all WebSocket sessions. Translates `setBreakpoints` source paths from virtual workspace paths (`/workspace/proj/Foo.java`) to real filesystem paths before forwarding to the DAP server. **`destroy()` sends `disconnect` with `terminateDebuggee:false` before closing the socket** — without this the DAP adapter calls `VM.exit()` and kills the JVM, making the JDWP port refuse the next attach.
-- `JavaDebugWebSocketHandler` — Spring WebSocket handler at `/websockets/ide/java-debug?workspace=<name>`. On open: `manager.getOrStart(username, workspace).addSession(session)`. On message: `bridge.sendToDap(json)`. On close: `manager.removeSession(sessionId)`.
-- `JavaDebugConfigEndpoint` — `GET /services/ide/java-debug/config` → `{"jdwpPort": N}`. The default port is `DirigibleConfig.JAVA_DEBUG_JDWP_PORT` (`DIRIGIBLE_JAVA_DEBUG_JDWP_PORT`, default `8000`).
-
-**OSGi requirement:** `com.microsoft.java.debug.plugin-*.jar` must be in the JDT.LS `plugins/` directory **and** listed in every `config_<platform>/config.ini` `osgi.bundles` entry. `JdtLsManager.installDebugPlugin()` handles both — it reads `Bundle-Version` from the jar's manifest and appends the entry. Without this, `vscode.java.startDebugSession` returns "unknown command".
-
-**Path translation:** the browser sends virtual paths like `/workspace/proj/Foo.java`; the DAP server needs real paths like `/home/user/.dirigible/repository/root/users/admin/workspace/proj/Foo.java`. `JavaDebugBridge.translateSourcePaths()` rewrites `setBreakpoints` requests. In the reverse direction, `realToVirtualPath()` in `debug.js` uses `lastIndexOf('/' + workspaceName + '/')` to strip the server prefix from stack-frame source paths.
-
-**Server-side LSP init:** `JdtLsInstance.ensureInitialized()` sends `initialize` + `initialized` to JDT.LS without a browser editor session so that `workspace/executeCommand` is not queued forever waiting for a client. Timeout: 60 s for `ensureInitialized`, 90 s for `startDebugSession` (CI runners are slow).
-
-### Frontend (`components/ui/view-java-debug`)
-
-- **Region:** `left` (sits alongside Projects/Import/Search in the left sidebar)
-- **Config:** `configs/debug-view.js` — `region: 'left'`, `lazyLoad: true`
-- **Layout:** compact toolbar (Attach, Disconnect, step controls) + status strip + three collapsible sections (Call Stack, Variables, Breakpoints)
-- **Workspace:** read from `localStorage[${getBrandingInfo().prefix}.workspace.selected]` on load; kept in sync via `platform.workspace.changed` hub topic (same source as the Projects view)
-- **Port:** fetched from `GET /services/ide/java-debug/config` on startup; falls back to 8000
-- **Host:** always `localhost` — not configurable from the UI
-- **Connecting animation:** `$interval` cycles through 18 descriptive phrases every 3 s while `status === 'connecting'`; cancelled on connected / error / disconnect / terminate / `$destroy`
-- **Breakpoints persistence:** stored in `localStorage['dirigible.java.debug.breakpoints']` as `{ virtualPath → int[] }`. Restored on load; `refreshBpList()` must be called after restoring to populate `$scope.bpList`.
-
-### Editor integration (`components/ui/editor-monaco`)
-
-- **`java.debug.highlight` topic:** `debug.js` posts `{ filePath: realPath, lineNumber }` when paused; editors match via `filePath.endsWith(myPath)`. Post is repeated after 1500 ms for newly opened tabs. `clearPausedState()` in `dapContinue()` posts `{ filePath: null, lineNumber: 0 }` immediately (the DAP `continued` event is optional and often skipped by the Java adapter for long-running JVMs).
-- **`java.debug.breakpoints` topic:** `debug.js` broadcasts the full `breakpoints` map; each editor restores glyph decorations for its own path. After registering its listener the editor immediately posts `java.debug.breakpoints.request` so the debug view re-broadcasts — this handles the race where the debug view's startup broadcast fires before the editor iframe is ready.
-- **Glyph CSS** (`editor.css`): `.debug-breakpoint-glyph` — red circle (14 × 14 px, `border-radius:50%`). `.debug-current-line-glyph` — right-pointing yellow triangle (CSS border trick, `#ffcc00`, 12 × 14 px). `.debug-current-line` — faint yellow line background.
-- **Glyph margin clicks:** `onMouseDown` with `isGlyphMarginLineNumber` toggles breakpoints and posts `java.debug.breakpoints.changed` with the updated lines array for that file.
-
-## Messaging perspective (`ide-messaging-monitoring` + `perspective-messaging`)
-
-A devops/debug surface for the embedded ActiveMQ broker — **embedded mode only**, see the broker-mode note below. Three modules cooperate:
-
-- **`components/ide/ide-messaging-monitoring`** — backend service + REST endpoint. Constructor-injects the `BrokerService` bean from `engine-listeners` (the broker is started with `useJmx=false` in `EmbeddedBrokerMessagingConfig`, so JMX is unavailable — read state directly off the bean instead). Both the service and the endpoint are `@Conditional(EmbeddedMessagingBrokerCondition.class)` — **with an external broker there is no `BrokerService` bean, so neither is registered and every endpoint here answers 404** (an external broker is administered from its own console). `RegionBroker.getDestinationMap()` enumerates queues and topics; `Destination.getDestinationStatistics()` exposes the counters; `Destination.browse()` returns the in-memory pending set without consuming. Endpoints live under `/services/ide/messaging-monitoring/` with `@RolesAllowed({ADMINISTRATOR, DEVELOPER, OPERATOR})`:
-  - `GET /summary` — broker meta + every queue/topic with counters
-  - `GET /queues/{name}/messages?limit=N` — non-destructive browse (capped at 200 by default, body preview at 64 KB)
-  - `DELETE /queues/{name}/messages` — purge
-  - `DELETE /queues/{name}/messages/{messageId}` — remove a single message
-  - `DELETE /queues/{name}` and `DELETE /topics/{name}` — remove the destination (returns 409 if consumers are still attached — `IllegalStateException` translated by the endpoint)
-- **`components/ui/perspective-messaging`** — perspective shell (id `messaging`, order 1010), icon, menu, extensions.
-- **`components/ui/view-messaging-destinations`** (left) and **`components/ui/view-messaging-browser`** (center) — filterable list of destinations and master-detail message inspector. They communicate over `MessageHub` topics `messaging.destination.selected` (selection broadcast), `messaging.destination.selection.request` (browser asks destinations view to re-broadcast on init — fixes the iframe-startup race), and `messaging.broker.refresh` (browser asks destinations view to re-poll after a mutating action). Confirm-dialogs go through `DialogHub.showAlert({type:'confirmation', buttons:[...]})`.
-
-**Topic limitation:** JMS topics do not retain non-persistent messages, so the browser shows live counters but no message list for topics. Message-body decoding prefers `ActiveMQTextMessage.getText()`; for `BytesMessage`-style payloads, the first 64 KB are inspected and rendered as UTF-8 when they look textual, otherwise base64-encoded.
-
-**Broker mode — embedded or external** (`engine-listeners/.../listeners/config/`). Set `DIRIGIBLE_MESSAGING_BROKER_URL` (plus optional `DIRIGIBLE_MESSAGING_BROKER_USERNAME` / `_PASSWORD`) and the platform stops starting its own broker and connects to that one instead — `tcp://`, `ssl://`, `failover:(…)`, e.g. Amazon MQ or a dockerized ActiveMQ shared by several deployments. Unset (or blank) keeps the previous behaviour exactly: an in-process `BrokerService` reached over `vm://localhost`.
-
-The two modes are two `@Configuration` classes — `EmbeddedBrokerMessagingConfig` and `ExternalBrokerMessagingConfig` — selected by `EmbeddedMessagingBrokerCondition` / `ExternalMessagingBrokerCondition`, which are the exact negation of one another, so exactly one always applies. Three things are worth knowing before touching this:
-
-- **The conditions read `DirigibleConfig`, not the Spring `Environment`** — deliberately, and this is the repo's only hand-written `Condition`. Dirigible resolves a key across its own layers and a value placed there programmatically (`Configuration.set`, which is how `ExternalMessagingBrokerIT` selects the mode) never reaches the `Environment`, so `@ConditionalOnProperty` would not see it. Conditions evaluate once per context refresh: an integration test must set the config in a static `@BeforeAll`, before the context is created.
-- **Both modes define the `ActiveMQConnection` and `ActiveMQSession` beans**; only the embedded one defines `ActiveMQBroker`. Nothing else changes, because every consumer — the `.listener` artifacts, the client-Java listeners (`engine-java`'s `ListenerClassConsumer`), `MessagingFacade` — reaches the broker through `ActiveMQConnectionArtifactsFactory`, which resolves the `ActiveMQConnectionFactory` **by type**. Swapping that one bean is the whole change; do not reintroduce a `@DependsOn("ActiveMQBroker")` outside the embedded config.
-- `DIRIGIBLE_MESSAGING_USE_DEFAULT_DATABASE` configures the embedded broker's persistence only and is logged as ignored in external mode. Anything else that reaches for the `BrokerService` bean must tolerate its absence (`ObjectProvider`, as `CloseActiveMQResourcesApplicationListener` does) or be conditional on the embedded mode (as the monitoring component is). An unreachable external broker fails startup on purpose.
-
-## External documentation
-
-The user-facing help portal at <https://www.dirigible.io/help/> documents the IDE perspectives (Workbench, Database, Git, Operations, Documents), artefact authoring (Jobs, CSVIM, Entity model, OData, Listeners, Camel routes, BPMN), JS/TS API reference (`/api/`), and deployment guides (Docker, Kubernetes, Cloud Foundry). Useful when reading integration-test fixtures under `tests/tests-integrations/src/main/resources/<TestName>/` or understanding what a given artefact extension is supposed to do.
-
-The portal is **a separate repository** — a VitePress 1.5 + Vue site built from <https://github.com/dirigible-io/dirigible-io.github.io>; that repo's own `CLAUDE.md` is the authority on its layout and rules. Doc fixes go there as PRs, not in this repo, and a merge to `master` deploys straight to www.dirigible.io via GitHub Actions. It migrated from Jekyll + six MkDocs instances in June 2026, so any guidance mentioning `docs-help/`, `mkdocs.yml`, or `blogs.json` is pre-migration and wrong. The current shape: help pages under `docs/help/**` (11 top-level sections; a new page also needs its sidebar entry in `docs/.vitepress/config.mts`), blog posts as single files `docs/blogs/YYYY/MM/DD/<slug>.md` with frontmatter (`title`, `description`, `author`, `author_gh_user`, `author_avatar`, `read_time`, `publish_date`) — the listing is generated by `docs/data/blogs.data.ts`, so no nav or index edits per post — and post images under `docs/images/<post-slug>/`, referenced relatively (`../../../../images/<post-slug>/…` from a post). House rules that bite: no em/en dashes anywhere in source (plain hyphens), VitePress admonitions (`::: tip`) not MkDocs (`!!!`), frontmatter on every page, absolute cross-links (`/help/...`), and `ignoreDeadLinks: true` masks broken links at build time — validate with `npm run docs:build` before pushing.
-
-The companion sample repos under `dirigiblelabs/*` are also separate. For end-to-end tests that clone such repos (`SampleProjectsIT` subclasses), the merge order follows the dependency direction, both ways: a dirigible-side IT that expects new sample content needs the sample-side PR merged first (else it clones an empty `master`), and a sample-side change that uses new platform APIs needs the platform PR merged first — the ITs clone the sample repo's HEAD, so merging the sample early breaks **every** PR's CI and master until the platform lands (this happened with the typed-handler interfaces: sample PR merged a day before platform PR [#6010](https://github.com/eclipse-dirigible/dirigible/pull/6010), and the Java entity-decorators verification failed across the board until #6010 merged). Re-running a failed PR check does NOT pick up a newer master — re-runs build the original merge snapshot; use `gh pr update-branch` (or push) to get a fresh merge.
-
-Treat `modules/commons/commons-config/src/main/java/org/eclipse/dirigible/commons/config/DirigibleConfig.java` (the enum) and `Configuration.java` (the allow-list) as the source of truth for env-var names and defaults, not the portal — the env-vars page lags the code by months. Specifically, the in-repo OAuth flow is Spring's `spring.security.oauth2.client.registration.github.*` activated by the `github` profile and configured via `DIRIGIBLE_GITHUB_CLIENT_ID` / `_CLIENT_SECRET` / `_SCOPE` (`build/application/src/main/resources/application-github.properties`), not the generic `DIRIGIBLE_OAUTH_*` entries some doc pages still describe. Current servlet mappings are rooted at `/services/...` and `/public/...` per `BaseEndpoint`; any `/services/v4/...` URL in a doc snippet is legacy.
-
-## CI reference
-
-`.github/workflows/build.yml` is the source of truth for "does this build pass" on **push to master**:
-
-- `code-style`: `mvn -T 1C formatter:validate`
-- `tests` (ubuntu + windows matrix): `mvn clean install -P unit-tests`
-- `integration-tests-h2` / `-postgresql`: the **full** Selenide IT suite, `mvn clean install -P integration-tests` with the matching `DIRIGIBLE_DATASOURCE_DEFAULT_*` env vars (MSSQL is no longer a CI leg — removed in #6150). Each DB leg is **sharded into four parallel matrix jobs** selected by tag expression — `api` (`!ui & !slow`), `ui` (`ui & !slow & !sample & !camel`), `samples` (`ui & !slow & (sample | camel)`), `slow` (`slow`) — so the run's wall clock is the slowest shard (~35 min, ~40 on PostgreSQL), not the whole ~1h40m suite. The shards partition the suite; keep them disjoint and complete when adding tags.
-- `build-deploy`: `mvn clean install -P quick-build` then Docker buildx multi-arch image push to `dirigiblelabs/dirigible`
-
-### PR gate vs full suite (smoke / nightly split)
-
-The full Selenide UI suite takes ~1.5h per DB, so it does **not** run on every PR:
-
-- **`pull-request.yml`** (every PR) runs `code-style`, unit `tests`, `docker-build`, and a single fast **`smoke-tests`** job on H2: `mvn clean install -P integration-tests -Dit.groups="!ui | smoke"`. The tag expression selects the HTTP-level ITs (untagged, so `!ui`) plus the few UI journeys explicitly marked `@Tag("smoke")` - including one full clone->generate->validate app lifecycle (`IntentEditorLoadsIT`, the intent Generate flow). Keep the smoke set small so the PR gate stays fast.
-- **`nightly.yml`** (cron `0 2 * * *` + `workflow_dispatch`) and **push to master** (`build.yml`) run the **full** suite on H2 + PostgreSQL.
-
-**Test tagging convention (JUnit 5 `@Tag`, wired to failsafe via the `${it.groups}` / `${it.excludedGroups}` properties in the root `pom.xml`):**
-- Every browser-driven IT is `@Tag("ui")` - inherited from the `UserInterfaceIntegrationTest` base (and thus by `SampleProjectsIT` and all sample-project ITs). Do not tag these individually.
-- HTTP-level ITs (`extends IntegrationTest` directly) carry no tag, so they are always in the smoke set.
-- To force a specific UI IT to run on every PR, add `@Tag("smoke")` to that class (keep the list small - smoke must stay fast).
-- Shard-routing tags: `@Tag("sample")` sits on the `SampleProjectsIT` base (inherited by every sample-project IT); `@Tag("camel")` sits on each IT in `ui/tests/camel` (their `PredefinedProjectIT` base is shared with non-camel tests, so the base cannot carry it — tag new camel ITs individually). These route classes into the `samples` CI shard; everything else UI stays in the `ui` shard.
-- `@Tag("slow")` is the **fourth shard**, and it is a *balancing* tag, not a semantic one: it holds the long poles of both families (currently the api classes above ~55 s and the browser journeys above ~110 s), because without them `api` and `ui` are the critical path while `samples` idles. Membership is a judgement about measured CI time — re-check it when the shard times drift apart, and note that mistagging can only unbalance the shards, never drop an IT (`api` is the untagged complement). It does **not** affect the PR smoke gate: a `slow` api IT is still untagged-`ui`, so `!ui | smoke` still selects it.
-
-`codeql.yml`, `release.yml` cover CodeQL and Maven Central release respectively.
+The guidance is split by topic into `.claude/docs/` and imported below (each file carries its own headings). Edit the topic files, not this index; add a new topic as a new file plus an import line here.
+
+@.claude/docs/behavioral-guidelines.md
+@.claude/docs/project-build-run.md
+@.claude/docs/repository-layout.md
+@.claude/docs/synchronizer-model.md
+@.claude/docs/client-java.md
+@.claude/docs/intent-layer.md
+@.claude/docs/model-generation.md
+@.claude/docs/harmonia-ui.md
+@.claude/docs/shells.md
+@.claude/docs/document-templates.md
+@.claude/docs/native-apps.md
+@.claude/docs/tenants.md
+@.claude/docs/conventions.md
+@.claude/docs/blimpkit.md
+@.claude/docs/java-debugger.md
+@.claude/docs/messaging.md
+@.claude/docs/external-docs.md
+@.claude/docs/ci.md