mxrb 0.1.0

data/docs/de-DE/scaffolds.md

@@ -0,0 +1,59 @@
+# Projekt-Scaffolds
+
+[Português](../pt-BR/scaffolds.md) · [English](../en-US/scaffolds.md) · **Deutsch**
+
+Alle Befehle akzeptieren `--target DIR`, überschreiben keine Dateien und
+verbinden `evaluate`/`evaluate_dir`-Aggregatoren automatisch. Mit
+`mxrb <Befehl> --help` werden Verwendung, Ziel und Optionen angezeigt.
+
+Verfügbar sind Projekt/Modul (`init`, `module new`), Domäne (`entity`,
+`enumeration`, `constant`), Anwendung (`use-case`, `validation`, `query`,
+`repository`, `scheduled-event`), Präsentation (`presentation init`, `page`,
+`nanoflow`), Sicherheit, Infrastruktur (`integration`, `published-rest`,
+`consumed-rest`, `java-action`), Prüfung (`functional-test`, `evaluation`),
+Design und GitHub-CI. `mxrb page new Modul.Seite` erzeugt weiterhin eine
+minimale Seite. Mit `--chain` entsteht ein ausführbarer vertikaler Schnitt mit
+Beispielentität, Data-Source-Microflow, editierbarer Seite, Aktionen und
+Responsive-Menüeintrag. Drei echte Mendix-Aktionsketten stehen zur Verfügung:
+
+```sh
+mxrb page new App.Order --chain page:microflow
+mxrb page generate App.Order --chain page:nanoflow
+mxrb page g App.Order --chain page:nanoflow:microflow
+```
+
+`page:microflow` ruft die Runtime direkt auf; `page:nanoflow` hält die Aktion
+auf dem Client; `page:nanoflow:microflow` verwendet den Client-Flow zur
+Orchestrierung eines Runtime-Aufrufs. Alle Modi erzeugen `ACT_LoadOrder` als
+Data Source. Ketten, die mit einem Microflow enden, erzeugen zusätzlich
+`ACT_RefreshOrder`. `page generate` und `page g` sind Aliase von `page new`.
+Jede erzeugte Kette wird als gültiges MPR materialisiert und durch den
+Compiler-Preflight geprüft.
+
+## Seitenvorlagen
+
+In Mendix sind Page Templates Ausgangspunkte, deren Struktur zu einer normalen,
+editierbaren Seite wird. MXRB listet nur durch Compiler und Runtime auditierte
+Muster:
+
+```sh
+mxrb page templates
+mxrb page templates --json
+mxrb page new App.Landing --template starter
+mxrb page new App.Empty --template blank
+mxrb page new App.Operations --template dashboard
+mxrb page new App.Order_NewEdit --template form-vertical
+```
+
+`form-vertical` erzeugt zusätzlich eine Beispielentität und eine
+`ACT_Load...`-DataView-Quelle. Jede Vorlage lässt sich mit `--chain`
+kombinieren; `--template dashboard --chain page:nanoflow` ergänzt zum Beispiel
+eine Client-Aktion. Diese Namen sind stabile, von Mendix-Mustern inspirierte
+MXRB-Verträge; sie behaupten nicht, alle installierten Atlas- oder Marketplace-
+Vorlagen still zu importieren. Siehe die [offizielle Seitendokumentation](https://docs.mendix.com/refguide/pages/).
+
+Artefaktbefehle verwenden `new Modul.Name`; Projektbefehle verwenden
+`design init` und `ci init github`. Alle unterstützten Entitätstypen und
+Assoziationen stehen in der [Entitäten-DSL](entity-dsl.md). Published REST und
+Java Action erzeugen editierbare Ruby-Adapter; das native Dokument bzw. die
+Aktion muss weiterhin aus einem exportierten Baseline oder Studio Pro stammen.

data/docs/de-DE/semantic-refactoring.md

@@ -0,0 +1,56 @@
+# Semantisches Refactoring
+
+[Português](../pt-BR/semantic-refactoring.md) · [English](../en-US/semantic-refactoring.md) · **Deutsch**
+
+Der semantische Index kombiniert typisierte Artefakte und BSON-Referenzen.
+`Project.Navigation` nimmt an Auswirkungsanalyse, Rename und Löschschutz teil.
+
+```ruby
+Mxrb.open("Shop.mpr", readonly: false) do |project|
+  plan = project.plan_rename("Sales.Home", to: "Landing")
+  plan.changes.each { puts _1.inspect }
+  plan.apply!
+end
+```
+
+Jedes Refactoring folgt Plan, Vorschau und `apply!`. Rename aktualisiert BSON
+und `_MxrbArchitecture` in derselben Transaktion. Remove blockiert Referenzen
+und Kind-Units; Move, Extract, Inline und Domänenmutationen zeigen Änderungen
+vor dem Schreiben.
+
+Der Analyzer findet fehlende Ziele, Profile ohne Startziel, doppelte Namen,
+unbekannte Benutzerrollen, Ziele ohne Zugriff, nicht aufgelöste Tokens und
+unzureichenden Kontrast. Der semantische Cache nutzt Unit-Fingerprints;
+`mxrb cache status`, `warm` und `clear` liefern Metriken und Wartung.
+
+`project.semantic_search_artifacts("Bestellung erstellen", limit: 5)` bietet
+deterministisches Ranking in Ruby. Das optionale Gem `sqlite-vec` beschleunigt
+die Suche in schreibbaren MPRs mit einem KNN-Index aus Backend, Dimension und
+Modell-Fingerprint. Der erste Aufruf füllt die Vektoren, bevor der Index als
+bereit markiert wird; schreibgeschützte Projekte und Plattformen ohne native
+Erweiterung behalten dieselbe In-Memory-API. Der bisherige CLI-Adapter lautet
+`mxrb find app.mpr "Bestellung erstellen" --semantic`. Der eigene Befehl
+stellt zusätzlich Backend, Ergebnislimit und Kosinusdistanz bereit:
+
+```sh
+bundle exec mxrb search "Zahlung" App.mpr
+bundle exec mxrb search "Bestellung erstellen" App.mpr --backend onnx --limit 5
+```
+
+Die Tabelle enthält Rang, Distanz, qualifizierten Namen und Typ; `--json`
+liefert dieselben Felder für Automatisierung.
+
+Für lokale ONNX-Entwicklung aktiviert `BUNDLE_WITH=onnx bundle install` die
+optionale Gruppe. `backend: :onnx` und das automatische Backend verwenden dann
+die dokumentierte Informers-`embedding`-Pipeline mit
+`sentence-transformers/all-MiniLM-L6-v2`. Ein eigener CI-Job setzt
+`MXRB_ONNX=1` und führt einen echten Smoke-Test mit 384 Dimensionen aus; die
+normale Installation und Testsuite laden das Modell nicht herunter.
+
+Der native sqlite-vec-Smoke-Test verwendet eine eigene Abhängigkeitsdatei für
+unterstützte Plattformen: `BUNDLE_GEMFILE=Gemfile.sqlite-vec bundle install`
+und danach `MXRB_SQLITE_VEC=1 BUNDLE_GEMFILE=Gemfile.sqlite-vec bundle exec
+rspec spec/semantic_search_spec.rb`. So bleibt das Haupt-Lockfile portabel,
+während CI die echte Erweiterung prüft.
+
+[Zurück zum Index](README.md)

data/docs/de-DE/team-server.md

@@ -0,0 +1,33 @@
+# Team Server
+
+MXRB verbindet sich ohne `mx`, Studio Pro oder Model SDK direkt mit offiziellen
+Team-Server-Git-Repositories und der App Repository API:
+
+```sh
+mxrb team-server login --pat-file /secure/team-server.env
+mxrb team-server projects --pat-file /secure/team-server.env
+mxrb team-server clone APP_ID ./app
+mxrb team-server branches APP_ID
+mxrb team-server pull ./app
+```
+
+`projects` paginiert die offizielle Projects API und liefert alle Projekte des
+Unternehmens. Anmeldedaten bleiben auf denselben HTTPS-Host begrenzt; ein vom
+Dienst gemeldeter HTTP-Redirect wird nur für genau denselben HSTS-Host auf HTTPS
+angehoben.
+
+Im empfohlenen Modus wird nur der absolute Pfad zur PAT-Datei gespeichert.
+Unterstützt werden Klartext, JSON und `.env` mit `MXRB_TEAM_SERVER_PAT`. Der PAT
+wird nur für Anfragen gelesen und Git über einen temporären `GIT_ASKPASS`-Helfer
+übergeben; er erscheint nie in URLs, Argumenten oder `.git/config`.
+
+Lesen benötigt `mx:modelrepository:repo:read`, Push zusätzlich
+`mx:modelrepository:repo:write`. Laut Mendix erhalten externe Klone nicht die
+gesamte Studio-Pro-Nachbearbeitung und Revisionsmetadaten. MXRB validiert
+MPR-Dateien nach Clone und Pull, kann aber keine Mendix-Cloud-Revisionsmetadaten
+erzeugen.
+
+Das Repository `a9e4af8a-2776-4b10-a471-8c42df8f5f43` wurde über die App
+Repository API abgefragt und per HTTPS geklont. MXRB validierte
+`MyFirstModule.mpr`, erkannte `main` und bestätigte eine Remote-URL ohne PAT.
+Die temporäre Zugangsdaten-Datei wurde anschließend zerstört.

data/docs/de-DE/validation-matrix.md

@@ -0,0 +1,64 @@
+# MXRB-Validierungsmatrix
+
+[Português](../pt-BR/validation-matrix.md) · [English](../en-US/validation-matrix.md) · **Deutsch**
+
+Stand: 5. August 2026.
+
+```text
+Original-MPR → validate → export → generate → validate → compare
+```
+
+| Projekt | Mendix | Format | Ergebnis |
+|---|---:|---|---|
+| QueryApiBlogPost | 7.17.0-rc5 | v1 | bestanden |
+| Sudoku | 11.12.1 | v2 | bestanden; 409 `.mxunit` |
+| MendixApp | 9.6.1 | v1 | bestanden |
+| ConnectorKitDemo | 7.5.0 | v1 | bestanden |
+| TreeviewDemo | 5.21.4 | v1 | bestanden |
+| GridViewPlayground | 6.10.8 | v1 | bestanden |
+
+## Tiefe Abdeckung
+
+Der Vergleich umfasst Metadaten, Security, Unit-Baum, Entitäten,
+Zugriffsregeln, Beziehungen, Seiten, Widgets, Events, Menüs und vollständige
+Microflow-/Nanoflow-Körper. 264 Flow-Körper und 1.304 Seitenknoten aus 25 Typen
+sind als bearbeitbares Ruby repräsentiert. Jede native Unit besitzt zusätzlich
+einen vollständigen bearbeitbaren Eintrag in `.mxrb/native_units.rb`.
+
+## Offizielle Gates
+
+Sudoku 11.12.1: **0 Fehler** in `mx check`, identische 23 Warnungen,
+1 Deprecation und 6 Empfehlungen; MxBuild erfolgreich. Mendix 6.10 baute
+Original und Rekonstruktion erfolgreich. 7.x und 9.6 zeigten diagnostische
+Parität. Die exakte 5.21-Prüfung bleibt wegen WPF auf Windows/Studio Pro eine
+ausdrückliche MXRB-Einschränkung und gehört nicht zum direkten automatischen
+Gate.
+
+## Semantik, Tests und Runtime
+
+- 1.778 Artefakte und 3.387 Referenzen;
+- 1.039 Beispiele, keine Fehler;
+- 100 % Zeilenabdeckung (17.224/17.224);
+- 100 % Branch-Abdeckung (6.811/6.811);
+- Sudoku-Modellbewertung: 7/7;
+- funktionale Runtime-Tests: 3/3 lokal und 3/3 in Docker.
+
+Ruby-Assertions prüfen Rückgabewerte und persistierte XPath-Anzahlen. Der
+Docker-Lauf bestätigte Games 1/2/3 und Cells 81/162/243; JUnit XML ist nur ein
+in Ruby erzeugtes CI-Format.
+
+Das 11.12.1-Gate enthält nun zusätzlich ein authentifiziertes Chromium-Szenario
+mit Login, Home-/Orders-Navigation, deterministischen DOM/Layout/Style/ARIA-
+Snapshots, Screenshots, explizitem SHA-256-Baseline-Vergleich, Fehlererkennung
+und echtem Logout. Alle drei `page --chain`-Pfade werden als gültiges MPR
+materialisiert und durch den Compiler-Preflight geprüft. Die mit
+`page --template` erzeugten Dashboard- und vertikalen Formularseiten wurden
+zusätzlich in der Runtime mit geprüftem berechnetem CSS ausgeführt.
+
+`script/validate_matrix` prüfte 1.506 Units in sechs Round-Trips in 14,760 s.
+`script/benchmark` maß 6,8463 s für die vollständige Sudoku-Pipeline.
+Deterministisches Fuzzing deckt 250 BSON-Dokumente und 50 atomare
+`.mxunit`-Dateien einschließlich Binärwerten ab.
+
+Die Matrix beweist die geprüften Szenarien, nicht universelle Kompatibilität
+mit jedem Mendix-Metamodell. Unbekannte `.mxunit`-Kodierungen werden abgelehnt.

data/docs/de-DE/vetclinic-acceptance.md

@@ -0,0 +1,24 @@
+# VetClinic-End-to-End-Abnahme
+
+Das Abnahmeprojekt wurde gelöscht, mit `mxrb init` neu erstellt und durchlief
+vor den Geschäftsregeln jeden Scaffold. Das Mendix-11.12.1-MPR bestand
+MXRB-Validierung und Lint, Architekturauswertung, offizielles `mx check`,
+`mxbuild` sowie einen Funktionstest im synchronisierten Runtime.
+
+Die Regression bestand 622 Beispiele mit 100 % Zeilen- und Branch-Abdeckung;
+RuboCop meldete keine Verstöße. Das Modell enthält Enumerationen, sechs
+Geschäftsentitäten, `System.User`-Generalisierung, Systemmitglieder,
+Zugriffsregeln, Indizes, N:1-, N:N- und 1:1-Beziehungen, Flows, Seite,
+Navigation und Scheduled Event.
+
+Scaffolds liefern Struktur, nicht die Geschäftsanforderungen. Attribute,
+Flow-Verhalten, Widgets, Rechte, Endpunkte, Tests und Auswertungen bleiben
+Projektarbeit. Beim abgenommenen VetClinic wurde die Navigation in `project.rb`
+ergänzt; `init` erzeugt nun Profil, Layout und Home-Seite minimal, während
+weitere Menüeinträge noch keinen eigenen Befehl haben.
+Published REST, Consumed REST und Java Action erzeugen baubare
+Microflow-Adapter; native Dokumente benötigen weiterhin ein exportiertes
+Baseline-Projekt oder Studio Pro.
+
+Ein unabhängiger Leerscaffold bestand ohne manuelle Änderung `mxrb validate`,
+das offizielle `mx check` und MxBuild.

data/docs/de-DE/writing.md

@@ -0,0 +1,138 @@
+# Projekte erstellen und bearbeiten
+
+[Português](../pt-BR/writing.md) · [English](../en-US/writing.md) · **Deutsch**
+
+`mxrb generate` wertet Ruby aus und erstellt oder aktualisiert ein MPR
+idempotent anhand stabiler Mendix-Namen.
+
+Ein leeres Verzeichnis kann direkt initialisiert werden:
+
+```sh
+mxrb init vet_clinic
+cd vet_clinic
+bundle install
+bundle exec mxrb generate project.rb
+bundle exec mxrb validate VetClinic.mpr
+```
+
+`init` akzeptiert snake_case oder PascalCase und erstellt `Gemfile`,
+`project.rb` sowie das Hauptmodul unter `modules/VetClinic`. Das Scaffold
+enthält nur Anwendungscode: `System` ist im Runtime implizit, Administration
+und Atlas sind Marketplace-Module. Bei einem vorhandenen Verzeichnis bricht
+der Befehl ohne Änderungen ab.
+
+Ein weiteres Anwendungsmodul wird im Projektstamm so hinzugefügt:
+
+```sh
+mxrb module new appointments
+```
+
+Der Befehl erstellt `modules/Appointments`, verwendet dasselbe Domain- und
+Application-Scaffold und bindet dessen `module.rb` in `project.rb` ein. Wenn
+das Modul bereits existiert oder die Projektdatei nicht sicher aktualisiert
+werden kann, wird der Vorgang atomar abgebrochen. Außerhalb des Projektstamms
+kann `--target DIR` verwendet werden.
+
+Artefakt-, Präsentations-, Infrastruktur-, Test-, Design- und CI-Generatoren
+sind im [Scaffold-Katalog](scaffolds.md) aufgeführt. Für Entitäten gilt die
+vollständige [Entitäten-DSL](entity-dsl.md).
+
+```ruby
+Mxrb.define("Shop.mpr") do
+  mendix_version "11.12.1"
+  self.module :Sales do
+    entity :Order do
+      string :Number, documentation: "Stabile Bestellnummer"
+      decimal :Total, default: 0
+    end
+  end
+end
+```
+
+```sh
+bundle exec mxrb generate shop.rb
+bundle exec mxrb validate Shop.mpr
+bundle exec mxrb export Shop.mpr exported-shop
+bundle exec mxrb compare original.mpr rebuilt.mpr
+```
+
+## Modellbewertungen und Funktionstests
+
+Bewertungen sind Ruby mit Checks wie `artifact`, `no_call_cycles` und eigenen
+Blöcken. Funktionstests verwenden ebenfalls Ruby:
+
+```ruby
+microflow "erstellt Bestellung",
+          call: "Sales.ACT_CreateOrder",
+          before: { call: "Sales.TEST_Prepare" },
+          after: { call: "Sales.TEST_Cleanup" },
+          expect: {
+            return: "true",
+            count: { entity: "Sales.Order", xpath: "[Status = 'Open']", equals: 1 }
+          }
+```
+
+`mxrb test App.mpr functional_test.rb --docker` führt Check, Build und Runtime
+in wegwerfbaren Containern aus. JUnit und MDL sind nicht nötig; das Original-MPR
+wird nie verändert.
+`--json ergebnis.json` und `--junit ergebnis.xml` erzeugen CI-Berichte. JUnit
+ist hier nur das XML-Austauschformat; MXRB schreibt es direkt in Ruby und
+installiert oder startet kein Java-JUnit-Framework.
+
+## Native Baseline
+
+Der Export schreibt `.mxrb/native_units.json` als verlustfreie Baseline und
+`.mxrb/native_units.rb` mit jedem BSON-Payload als bearbeitbaren Ruby-Hash.
+`native_unit`, `deep_structure` und `bson_binary` machen auch Bilder,
+Konstanten, Datensätze, Dienste, Einstellungen, Vorlagen und neue Mendix-Typen
+direkt bearbeitbar. Ruby-Änderungen überlagern die Baseline vor den typisierten
+Writes. `body_fingerprint` verwendet unveränderte native Graphen exakt wieder
+und regeneriert sie nach Ruby-Änderungen.
+
+## Ruby-Modul-Marketplace
+
+```sh
+mxrb module search
+mxrb module search security
+mxrb module add shared-kernel
+mxrb module add ./lokales-paket --target ./exportiertes-projekt
+```
+
+JSON-Kataloge kommen aus der Gem, von einem lokalen Pfad oder über HTTPS mit
+`--registry`. Pakete besitzen `mxrb-module.json` und können eingebaut, lokal
+oder Git-basiert sein. Die Installation nutzt Staging, lehnt unsichere Pfade ab
+und schreibt Version, Quelle, Ref und SHA-256 nach
+`.mxrb/modules.lock.json`.
+
+## Seiten, Navigation, Security und MPR v2
+
+Core-Widgets haben kompakte Methoden, einschließlich `text_area` und Widgets
+innerhalb einer `tab_page`. Sie verwenden das moderne Forms-Modell von Mendix
+11. `data_grid` erzeugt Data Grid 2; `drop_down` und `reference_selector`
+erzeugen Combo Box Widgets.
+
+Pluggable Widgets benötigen ihre `.mpk`-Pakete im Projektverzeichnis
+`widgets/`. Danach synchronisiert
+`bundle exec mxrb widgets sync project.rb MeineApp.mpr` das versionsabhängige
+Schema und wendet die Ruby-Eigenschaften an. Weitere MPKs lassen sich mit
+`pluggable_widget` deklarieren. Unbekannte importierte Widgets bleiben als
+`native_widget` mit editierbarer `deep_structure` vollständig erhalten.
+Importierte Seiten bieten ebenfalls `deep_structure({...})`. Menüs und
+Security sind bearbeitbar. Bei MPR v2 erzeugt MXRB automatisch
+`mprcontents/*.mxunit`.
+
+## Semantische Werkzeuge
+
+CLI-Befehle: `refs`, `callers`, `callees`, `impact`, `rename`, `remove`,
+`move`, `lint`, `report`, `diff`, `find`, `describe` und `tree`. Das eingebaute
+Lint prüft Zugriffsregeln persistenter Entitäten, Rollen von Seiten/Flows,
+Dokumentation öffentlicher Verträge, Navigationsziele und doppelte
+Modulrollenzuordnungen. `mxrb cache status|warm|clear app.mpr` liefert
+Cache-Metriken und Wartung.
+Refactorings schreiben erst mit `--apply`; Verschiebungen bleiben im selben
+Modul und verhindern Ordnerzyklen.
+
+Bei `readonly: false` speichert der erste Aufbau einen kompakten,
+fingerprint-basierten semantischen Index im MPR. Spätere Öffnungen verwenden
+ihn nur, solange Inhalte und Containment unverändert sind. Schreibgeschützte
+Projekte können einen vorhandenen Cache lesen, erstellen ihn aber nicht.

data/docs/en-US/README.md

@@ -0,0 +1,24 @@
+# MXRB documentation
+
+[Português](../pt-BR/README.md) · **English** · [Deutsch](../de-DE/README.md)
+
+- [Project architecture](architecture.md)
+- [Architectural standard](architectural-standard.md)
+- [Project structure](project-structure.md)
+- [Architectural patterns](architectural-patterns.md)
+- [Semantic refactoring](semantic-refactoring.md)
+- [Navigation and design system](design-system.md)
+- [OQL, SQL views, and the local database](oql-sql.md)
+- [Conventions](conventions.md)
+- [Ruby-first roadmap](ruby-first-roadmap.md)
+- [Validation matrix](validation-matrix.md)
+- [Native compiler and Runtime](compiler.md)
+- [Native build and Runtime quality report](native-runtime-quality-report.md)
+- [Writing projects](writing.md)
+- [Project scaffolds](scaffolds.md)
+- [Entity DSL](entity-dsl.md)
+- [Operations, lifecycle, and Marketplace](platform-operations.md)
+- [Mendix API integration assessment](platform-api-integration.md)
+- [VetClinic end-to-end acceptance](vetclinic-acceptance.md)
+
+[Back to the project README](../../README.md)

data/docs/en-US/architectural-patterns.md

@@ -0,0 +1,151 @@
+# Architectural patterns
+
+[Português](../pt-BR/architectural-patterns.md) · **English** · [Deutsch](../de-DE/architectural-patterns.md)
+
+This page collects the engineering patterns MXRB applies consistently. They
+explain *why* the public API looks the way it does and what guarantees each
+pattern buys. For the module layout itself, see
+[project structure](project-structure.md).
+
+## 1. Ruby-first, single public interface
+
+Ruby is the only public language. Everything MXRB can do is reachable from
+`Mxrb` module functions and the `Project` object they return:
+
+```ruby
+Mxrb.open("Shop.mpr", readonly: false) do |project|
+  project.find_artifact("Sales.Order")
+  project.plan_rename("Sales.Order", to: "Invoice").apply!
+end
+```
+
+There is no MDL, no parallel query language and no second configuration
+syntax. Project-specific lint rules, evaluations and functional tests are
+ordinary Ruby files too. External Mendix tools (`mx`, MxBuild, the Runtime)
+are optional compatibility gates executed afterwards — never a runtime
+dependency of the Ruby core.
+
+## 2. The CLI is a thin adapter
+
+`bin/mxrb` parses arguments, calls the Ruby API and prints results. It holds
+no logic of its own. Every command is a one-line delegation:
+
+- `mxrb generate` → `Mxrb.define`
+- `mxrb export` → `Mxrb::Exporter`
+- `mxrb validate` → `Mxrb::Integrity::Validator`
+- `mxrb compare` / `mxrb diff` → `Mxrb.compare`
+- `mxrb rename|remove|move ... [--apply]` → `project.plan_*` (+ `apply!`)
+- `mxrb refs|callers|callees|impact` → the semantic index
+- `mxrb lint` / `mxrb report` → `project.analyze`
+- `mxrb evaluate` → `Evaluation::Suite`
+- `mxrb test` → the functional runtime executor
+- `mxrb module search|add` → the marketplace catalog and installer
+
+A consequence: anything shown in this documentation as a CLI command has an
+equivalent, more expressive Ruby form. When in doubt, trust the Ruby API.
+
+## 3. Typed DSLs over a lossless baseline
+
+MXRB never discards what it cannot yet express concisely. Export writes two
+baseline files beside the project:
+
+- `.mxrb/native_units.json` — the original BSON payloads, lossless.
+- `.mxrb/native_units.rb` — every payload expanded as editable Ruby
+  (`native_unit` + `deep_structure` hashes, binary values as `bson_binary`).
+
+Generation restores the baseline first, then overlays the typed structures
+that Ruby explicitly owns. Editing the deep Ruby hash overrides the baseline
+before typed writers run. Images, constants, datasets, services, project
+settings, templates and even unit types introduced by future Mendix versions
+therefore survive round trips and stay editable, without waiting for a typed
+abstraction to exist.
+
+## 4. Fingerprint-based flow reuse
+
+Every exported flow body carries a canonical `body_fingerprint`:
+
+- Body unchanged → the exact native graph is reused byte-for-byte.
+- Body edited → the fingerprint no longer matches and the writer regenerates
+  that flow graph.
+
+This keeps round trips stable while making edits deterministic: a change in
+Ruby always wins over the stored native form, and untouched flows are never
+accidentally rewritten.
+
+## 5. Plan / preview / apply! for every mutation
+
+No semantic operation writes on first contact. Each one builds a plan:
+
+```ruby
+Mxrb.open("app.mpr", readonly: false) do |project|
+  plan = project.plan_rename("Sales.Order", to: "Invoice")
+  plan.changes.each { puts "#{_1.path.join(".")}: #{_1.before} -> #{_1.after}" }
+  plan.apply! # the only line that writes
+end
+```
+
+Guarantees shared by rename, remove, move, extract, inline and domain
+mutation plans:
+
+- full preview of changes and affected units before anything is written;
+- validation up front (name rules, collisions, references, child units,
+  container legality);
+- `apply!` writes inside an MPR transaction, so a failure mid-apply leaves
+  the database unchanged;
+- the semantic index is rebuilt after applying;
+- re-applying an already-applied plan is blocked;
+- the CLI previews by default and only writes with `--apply`.
+
+See [semantic refactoring](semantic-refactoring.md) for each operation.
+
+## 6. Atomic `.mxunit` writes (MPR v2)
+
+In v2 projects, unit contents live in
+`mprcontents/aa/bb/<uuid>.mxunit`. Writes go to a temporary file in the same
+directory followed by an atomic rename; SQLite keeps `Contents` null and
+stores only the content hash. Readers never observe a half-written payload.
+Non-BSON `.mxunit` encodings are rejected explicitly — MXRB raises rather
+than guessing.
+
+## 7. Transactions and rollback at the storage boundary
+
+`apply!` implementations wrap their mutations in the MPR transaction. The
+marketplace installer follows the same philosophy on the file system: it
+installs into a staging directory, moves the previous module to a backup
+location during update, and restores it if the final move fails.
+
+## 8. Marketplace: catalog → staging → lockfile
+
+Module installation is deliberately boring and auditable:
+
+1. A JSON catalog (built-in, local path or HTTPS via `--registry`) resolves a
+   name to a package source: built-in, local directory or Git repository.
+2. Files are copied into a staging directory; path traversal outside the
+   target is rejected.
+3. Dependency and Mendix-version requirements from `mxrb-module.json` are
+   checked before writing.
+4. `.mxrb/modules.lock.json` records version, source, ref and a SHA-256
+   digest of the installed files.
+
+```sh
+bundle exec mxrb module search security
+bundle exec mxrb module add shared-kernel --target ./my-project
+```
+
+## 9. Errors are typed and explicit
+
+The `Mxrb::Error` hierarchy separates storage problems (`NotMprError`,
+`SchemaError`, `SerializationError`) from usage problems (`ReadOnlyError`,
+`ValidationError`) and from toolchain/marketplace failures. Unknown encodings
+and corrupt structures raise; they are never silently repaired or dropped.
+Preservation of an unknown structure is a compatibility mechanism, not data
+loss — but rejection of an unknown *encoding* is a hard stop, because writing
+back a guess would corrupt the project.
+
+## 10. Coverage as a gate, not a metric
+
+CI enforces 100% line and 100% branch coverage through Ruby's native
+`Coverage` API. The local helper defaults to 100/100 when no threshold
+variables are supplied.
+The gate measures every executable library line and branch; comments such as
+`:nocov:` do not remove code from the denominator. See [conventions](conventions.md).

data/docs/en-US/architectural-standard.md

@@ -0,0 +1,89 @@
+# MXRB architectural standard
+
+[Português](../pt-BR/architectural-standard.md) · **English** · [Deutsch](../de-DE/architectural-standard.md)
+
+## 1. Central principle
+
+Ruby is the canonical representation of architecture. Mendix remains the
+execution platform and native model; MXRB must preserve compatibility without
+forcing platform internals into application code.
+
+## 2. Complete structure
+
+Applications are split into app-level security/navigation and modules with
+`domain`, `application`, `presentation`, `infrastructure` and module security.
+Large presentation areas use vertical feature slices.
+
+## 3. Flow mapping
+
+- Domain rules express entity-level invariants.
+- Application microflows implement use cases, queries, validations and jobs.
+- Presentation nanoflows implement client interaction.
+- Infrastructure flows implement services, adapters and integrations.
+- Events and callbacks point to these responsibilities instead of defining a
+  second architecture.
+- `uses_repository`, `calls`, lifecycle and data-source declarations feed the
+  semantic dependency graph.
+
+A microflow is classified by responsibility, not by being a microflow.
+
+## 4. Allowed dependencies
+
+`presentation` and `infrastructure` may depend on `application`; application
+may depend on domain. Domain does not depend on outer layers. Cross-module
+access should use a declared public API.
+
+## 4.1 Queries, repositories and Mendix persistence
+
+Direct Mendix retrieval is appropriate for ordinary CRUD. A repository is
+introduced when it represents a meaningful port: external storage, a complex
+query contract, test isolation or an architectural boundary.
+
+## 5. Public module API
+
+Artifacts intended for other modules are explicitly public. Internal
+microflows and entities are not treated as contracts merely because their
+qualified names are discoverable.
+
+## 6. Security
+
+App security owns user roles and project-wide policy. Module security owns
+module roles. Pages, microflows and nanoflows declare allowed module roles.
+Unknown native security settings are preserved until they have a typed Ruby
+representation.
+
+## 7. Navigation
+
+Navigation is application-level. Menus preserve translations, nested items and
+native actions through concise DSL plus authoritative deep structures.
+
+## 8. Design system
+
+Semantic Ruby tokens describe intent; Mendix resources implement it. Native
+themes, images and design properties remain preserved even when no concise DSL
+exists yet.
+
+## 9. Design patterns
+
+Use-case, query, adapter, strategy and policy objects are encouraged when they
+clarify a boundary. Avoid ceremonial layers around native Mendix behavior.
+
+## 10. Naming
+
+Mendix-qualified names are canonical. Ruby files use `snake_case`; classes and
+symbols may adapt names without changing Mendix identity.
+
+## 11. Automatable quality rules
+
+MXRB can enforce missing references, forbidden dependencies, cycles, access
+boundaries, naming policy, unreferenced-artifact thresholds and custom Ruby
+checks. Official `mx check` and MxBuild remain final platform gates.
+
+## 12. Current support boundary
+
+Typed domain, microflow and nanoflow, page, menu, security, and native
+navigation surfaces are editable. Theme and code assets use a checksummed
+manifest; design-system tokens and policies have a typed Ruby contract.
+Workflows, integrations, published APIs, and widgets without a concise API
+remain editable through deep Ruby and the native baseline, but still need
+specific typed DSLs.