mxrb 0.1.0

data/docs/en-US/native-runtime-quality-report.md

@@ -0,0 +1,73 @@
+# Native build and Runtime quality report
+
+Date: August 5, 2026.
+
+## Confirmed result
+
+- no functional stage invokes `mx`, `mxbuild`, `mxcli`, Studio Pro, or Model SDK;
+- clean 12-stage build and web generation passed on 6.10.8 (39 pages), 7.5.0 (45), 7.17.0 (66), 9.6.1.29396 (90), 10.24.0.73019 (optimized client), and 11.12.1;
+- format round-trip matrix passed on six real fixtures from 5.21.4 through 11.12.1: 1,506 units, 1,734 artifacts, and 3,388 references;
+- audited compiler schemas/seeds cover families 6.x, 7.x, 9.x, 10.x, and 11.x. Families 5.x and 8.x fail closed for native compilation; Runtime requires the exact patch;
+- Data Grid 1 covers database/XPath/microflow sources, search, sorting, paging, selection, and audited buttons. Data Grid 2 covers XPath, attribute columns, and create action;
+- web profiles are Dojo on 6/7, hybrid Dojo/React on 9, project-selected classic/optimized on 10, and React on 11;
+- Projects API inventoried 130 accessible apps. Three real Git projects (`MyFirstModule`, `LearnNow Trainning Management`, and `SLATaskApp`) passed validate → export → generate → validate → compare;
+- `MyFirstModule` was regenerated as exact 11.12.1 without proprietary builders. Runtime synchronized 655 database operations, created the active `mx` administrator, served the React shell and styled login publicly on `127.0.0.1:18080`, and exposed the expected domain tables;
+- a from-scratch optimized-client 10.24.0.73019 application passed official `mx check` and `mxbuild`, native model/Java/Rollup/portable packaging, 460 database synchronization operations, readiness probe and HTTP 200;
+- authenticated Chromium QA passed repeatedly across Home and Orders with
+  deterministic DOM/layout/style/ARIA snapshots and screenshots, zero console
+  errors, and an explicit SHA-256 baseline;
+- `mxrb page new|generate|g Module.Page --chain ...` materializes valid MPRs
+  for `page:microflow`, `page:nanoflow`, and `page:nanoflow:microflow`; without
+  the option, the minimal page scaffold remains unchanged;
+- `mxrb page templates` exposes the starter/blank/dashboard/form-vertical tree;
+  `--template` composes those templates with chains, and dashboard/form-vertical
+  passed in a real Runtime with compiled theme CSS and zero console errors;
+- final QA: 1,039 examples, zero failures, 100.00% lines (17,224/17,224), 100.00% branches (6,811/6,811), and clean RuboCop across 244 files.
+
+## Corrections from the improvement report
+
+- selective Java proxy generation for entities, inheritance, enumerations, and constants referenced by custom Java;
+- official Database Connector build-extension lowering to External Database Connector Java actions, including safe query-builder `SELECT` generation;
+- OQL view source compilation, generalized entity persistence flags, demo-user role arrays, system texts, and exact association storage/access rights;
+- stable PostgreSQL readiness, public loopback Runtime port (`--runtime-port`), environment-backed admin password, and active admin creation;
+- self-contained login resources, rendered template placeholders, cache busting, and styled/i18n login shell;
+- Atlas CSS, manifest, and public-asset hydration; the real Team Server
+  homepage now renders actionable React grids, headings, and buttons;
+- React developer-mode page imports carry the session cache token; the patched
+  client chunk is content-hashed and Rspack's self-import shares the entrypoint
+  token, eliminating stale blank-homepage reloads without disabling cache;
+- the generated shell supplies a bounded `openForm` compatibility adapter over
+  `openForm2`, so cached legacy click handlers navigate instead of failing
+  silently without issuing a Runtime request;
+- the official React Gallery now renders XPath and microflow data, item
+  templates, selection, and formatted string/numeric values. Authenticated
+  browser QA rendered the persisted course title, description, `90 day(s)`,
+  and `49.95`, while an empty Teacher Gallery remained structurally present;
+- nanoflow list/object sources and button actions now compile to the real
+  Mendix client property contracts and function-backed instruction programs.
+  The audited graph subset includes decisions, error paths, nested nanoflows,
+  JavaScript actions and server microflow calls; unsupported client nodes fail
+  closed instead of being mislabeled as microflows;
+- the PostgreSQL workspace injects a coherent JDBC URL and the Runtime SSL
+  option; `CheckNothing` navigation roles, scroll modes, SidebarToggle, and
+  microflow data-source return constants follow the real 11.12.1 client
+  contracts observed during authenticated testing;
+- real browser clicks verified Home → Courses → Add → Save. Parameter-backed
+  DataView/TextBox forms render and persist values; create passes GUIDs through
+  `openForm2`, while commit/rollback authorization is derived from page module
+  roles. PostgreSQL confirmed the four saved QA values;
+- template/image/ZIP traversal and unsafe identifier protection, plus symlink rejection for native inputs;
+- comparison normalizes absent Runtime boolean defaults, restoring exact legacy round trips.
+
+## Explicit boundaries
+
+1. Dojo widgets other than Data Grid 1 remain listed in `web/mxrb-legacy-pages.json`; they are not silently reported as rendered.
+2. Data Grid 2 coverage is the audited XPath/attribute/create subset. Gallery
+   covers XPath/microflow and the audited nanoflow graph subset. Unsupported
+   graph shapes, missing action/flow references, unsafe parameter mappings and
+   untranslated client instructions still fail closed.
+3. Installed 6/7/9 distributions contain exact Runtime bundles but no compatible launcher. The available 11 launcher requires Java 21 and cannot safely start 9 on Java 11. Legacy `db up` therefore fails closed; exact boot is claimed for 10.24.0.73019 and 11.12.1 only.
+4. Runtime uses a local trial/developer license, which emits the expected time-limit warning.
+5. Cloud Build/Deploy/Pipelines/Backups are optional external verification adapters, never dependencies of native generation or Runtime startup.
+
+There is no hidden `mx`/`mxbuild` fallback.

data/docs/en-US/oql-sql.md

@@ -0,0 +1,201 @@
+# OQL, SQL views, and the local database
+
+MXRB exposes OQL only when the native model contains it. It discovers OQL
+dataset sources and view-entity queries; an app without OQL returns an empty
+collection and does not gain synthetic query documents.
+
+## Static inspection
+
+```ruby
+Mxrb.open("Shop.mpr") do |project|
+  next unless project.oql?
+
+  project.oql_queries.each do |query|
+    puts query.qualified_name
+    puts query.oql
+    puts query.parameters
+  end
+
+  project.oql_sql_views(dialect: :postgresql).each do |view|
+    puts view.sql if view.supported?
+    warn view.warnings.join("\n")
+  end
+end
+```
+
+The CLI provides the same typed result:
+
+```sh
+bundle exec mxrb oql Shop.mpr
+bundle exec mxrb oql Shop.mpr --dialect ansi
+bundle exec mxrb oql Shop.mpr --dialect sql_server --json
+```
+
+The SQL view is deliberately read-only. Parameters such as `$Customer` become
+named binds such as `:Customer`; values are never interpolated. String literals
+and comments remain opaque. Multiple statements and OQL bulk writes are
+rejected.
+
+Generated SQL has `logical` confidence. PostgreSQL and SQL Server views use the
+conventional `module$entity` table shape, while ANSI keeps `Module.Entity`.
+Always verify physical table and column names against the database created by
+the exact Mendix Runtime. Association-path joins are reported as unsupported
+until Runtime storage metadata can prove the correct join.
+
+## Dialect-aware analysis
+
+`Oql::Analyzer` detects cost and portability patterns in the original source,
+preserves the triggering fragment for highlighting, and returns actionable
+alternatives for PostgreSQL, SQL Server, and ANSI:
+
+```ruby
+report = Mxrb::Oql::Analyzer.new(dialect: :postgresql)
+                            .analyze_source("SELECT * FROM Sales.Order")
+report.findings.each { puts "#{_1.rule}: #{_1.suggestions[:postgresql]}" }
+
+reports = Mxrb.open("Shop.mpr") { _1.oql_analysis(dialect: :postgresql) }
+```
+
+Rules cover leading and both-sided wildcards, prefix searches,
+`LOWER`/`UPPER`/`CAST` in `WHERE`, Cartesian products, and `SELECT *`.
+Findings are `hint`, `warning`, or `error`; `clean?` means no errors.
+
+The CLI handles native OQL plus both OQL and SQL ad-hoc sources:
+
+```sh
+bundle exec mxrb analyze Shop.mpr --dialect postgresql
+bundle exec mxrb analyze --oql "SELECT * FROM Sales.Order"
+bundle exec mxrb analyze --sql "SELECT * FROM sales$order" --json
+```
+
+## Real plans and database performance
+
+Static analysis cannot prove which path the optimizer will choose. In the
+materialized PostgreSQL workspace, MXRB also requests the real planner JSON and
+correlates plan relations with `pg_indexes`:
+
+```sh
+bundle exec mxrb db explain Shop.mpr \
+  "SELECT * FROM \"sales$order\" WHERE status = 'Open'"
+bundle exec mxrb db explain Shop.mpr \
+  "SELECT * FROM \"sales$order\" WHERE status = 'Open'" --analyze --json
+```
+
+The default mode uses `EXPLAIN` and does not execute the query. `--analyze` is
+explicit because it uses `EXPLAIN ANALYZE`; the query runs through the
+read-only role and includes timings and buffers. The report distinguishes
+small sequential scans, which may be optimal, from large scans. It also flags
+heavy filter discard, cardinality misestimates, high-volume nested loops, and
+sorts that spill to disk. Existing indexes are included as evidence, but MXRB
+does not invent `CREATE INDEX` statements without workload and selectivity
+evidence.
+
+The cumulative PostgreSQL workload can also be inspected:
+
+```sh
+bundle exec mxrb db workload Shop.mpr --limit 50
+bundle exec mxrb db workload Shop.mpr --limit 50 --json
+```
+
+The workspace enables `pg_stat_statements` and `track_io_timing`. The report
+ranks query fingerprints by cumulative cost and analyzes mean latency, cache
+hits, I/O, temporary blocks, and rows per call. Table statistics expose
+sequential-scan pressure; large non-unique indexes with no observed scans are
+also flagged. Because these metrics are cumulative since the statistics reset,
+index removal is never suggested without confirming the real window and
+workload.
+
+For a SQL Server deployment, the connection is explicit and uses `sqlcmd`:
+
+```sh
+export MXRB_SQLSERVER_PASSWORD='secret'
+bundle exec mxrb db explain Shop.mpr \
+  "SELECT * FROM dbo.[Order] WHERE Status = 'Open'" \
+  --engine sql_server --server db.example:1433 \
+  --database Shop --user mxrb_analyst --json
+```
+
+Estimated mode uses `SHOWPLAN_XML`; `--analyze` uses `STATISTICS XML` and
+executes only one `SELECT`/`WITH`. The parser detects large table/clustered
+scans, high-volume nested loops, tempdb spills, cardinality divergence, and
+missing-index hints. Those hints remain optimizer hypotheses, not automatic
+DDL. The password travels in `SQLCMDPASSWORD`, never argv. The engine is not
+inferred from the MPR because it belongs to deployment configuration.
+
+## Materialized local PostgreSQL
+
+An MPR contains the application model, not an application-data snapshot. The
+Mendix Runtime owns the database schema and synchronizes it from the model.
+MXRB can build the exact portable Runtime, start an isolated PostgreSQL, let
+the Runtime perform that synchronization, and expose SQL access:
+
+```sh
+bundle exec mxrb db up Shop.mpr
+bundle exec mxrb db status Shop.mpr
+bundle exec mxrb db sql Shop.mpr \
+  'SELECT * FROM "sales$order" LIMIT 20'
+bundle exec mxrb db shell Shop.mpr
+```
+
+After changing the MPR, rebuild and synchronize while retaining the data:
+
+```sh
+bundle exec mxrb db sync Shop.mpr
+bundle exec mxrb db down Shop.mpr
+```
+
+`db down` stops the containers but preserves the PostgreSQL volume. A later
+`db up` reuses both the package cache and the data. The host port defaults to
+`127.0.0.1:55432` and can be changed with `--port`.
+
+Local tools can access the same workspace through a JSON HTTP endpoint:
+
+```sh
+bundle exec mxrb serve Shop.mpr --port 4567
+curl -X POST http://127.0.0.1:4567/query \
+  -H 'Content-Type: application/json' \
+  -d '{"sql":"SELECT * FROM \"sales$order\" LIMIT 20"}'
+```
+
+The body accepts exactly one `sql` or `oql` field. Ad-hoc OQL passes through
+the safe PostgreSQL translator; parameterized queries and anything other than
+one `SELECT`/`WITH` statement are rejected. Responses include `rows`,
+`row_count`, `elapsed_ms`, warnings, or a structured error. The server binds
+only to loopback, uses `mxrb_reader`, and prepares the workspace by default;
+`--no-up` reuses an already-running workspace.
+
+Permanent cleanup is intentionally explicit:
+
+```sh
+bundle exec mxrb db destroy Shop.mpr --yes
+```
+
+It removes only resources carrying the matching MXRB ownership label.
+
+## Security boundary
+
+- PostgreSQL is bound only to loopback.
+- Each absolute MPR path receives separate containers, network, volume, and
+  state.
+- Random credentials live under the user's XDG state directory with mode
+  `0600`, outside the project repository.
+- `db sql`, `db shell`, and `db url` use `mxrb_reader`, whose transactions and
+  role default are read-only.
+- `mxrb_reader` receives `pg_read_all_stats` inside the isolated workspace so
+  Runtime fingerprints can be correlated; this grants no application-data writes.
+- `--write` explicitly selects the Runtime owner role. Direct writes can break
+  Mendix invariants and should be exceptional.
+- The PostgreSQL workspace never targets an existing remote database. SQL
+  Server plan analysis is a separate, explicit deployment connection; use a
+  read-only login with SHOWPLAN permission. Its password stays in an environment
+  variable and mutating keywords are rejected, including writable CTEs.
+
+The exact Mendix toolchain and Docker daemon must be available. SQL Server
+plans additionally require `sqlcmd`. Schema
+synchronization can change or reject existing data when the model changes, so
+back up any valuable local volume before risky model migrations.
+
+See the official Mendix documentation for
+[OQL](https://docs.mendix.com/refguide/oql/),
+[data storage](https://docs.mendix.com/refguide/data-storage/), and
+[Runtime database settings](https://docs.mendix.com/refguide/custom-settings/).

data/docs/en-US/platform-api-integration.md

@@ -0,0 +1,36 @@
+# Mendix API integration assessment
+
+Date: August 1, 2026. Source: the official [Mendix APIs and SDK index](https://docs.mendix.com/apidocs-mxsdk/).
+
+## Decision matrix
+
+| API or SDK | MXRB use | Decision |
+| --- | --- | --- |
+| Projects API | list accessible apps and project metadata | integrated as `team-server projects`; read-only by default |
+| App Repository API | repository info, branches, and commits | integrated in Team Server discovery and clone flow |
+| Marketplace Content API | discover and download modules/widgets | integrated in Marketplace operations |
+| Build API | compare a native MXRB artifact with an official cloud build | optional external verification adapter; never a native-build dependency |
+| Deploy API v4 | inventory apps/environments before release verification | proposed read-only adapter; mutations require explicit confirmation |
+| Pipelines API | trigger and observe an existing CI/CD pipeline | proposed opt-in adapter with idempotency and status polling |
+| Backups API v2 | list/create/download snapshots before deployment work | proposed safety adapter; restore/delete remain explicit destructive actions |
+| Runtime API 11 | compile custom Java and verify Runtime contracts | used as a contract for proxy generation; it is a Java API, not a remote REST replacement |
+| Client and Pluggable Widget APIs | define Dojo/React/Data Grid bundle contracts | reference contract for generated web artifacts, not an HTTP client |
+| Catalog APIs | register or query governed external data sources | future plugin; outside native build/runtime |
+| Model/Platform SDKs and Studio Pro extensibility | remotely model apps or extend Studio Pro | deliberately not required; MXRB remains Ruby/SQLite/BSON and standalone |
+
+## Integration rules
+
+- Remote calls are explicit; `generate`, `compile`, `validate`, and `db up` never contact Mendix Cloud.
+- PATs/API keys come from a protected file or environment and are never written to reports, logs, generated projects, or Git.
+- Read-only endpoints are the default. Build, deploy, pipeline, backup restore, project membership, and deletion operations require a dedicated command and confirmation appropriate to their impact.
+- The Build API is limited to Mendix Cloud apps and uses account API-key authentication, so it cannot replace MXRB's local native compiler.
+- Versioned Runtime and frontend APIs are compatibility evidence. MXRB keeps exact audited schemas/seeds and fails closed when a version contract or launcher is unavailable.
+
+## Recommended order
+
+1. App Repository branch/commit listing in `team-server`, completing the already integrated repository discovery.
+2. A read-only Deploy inventory command and optional Build comparison gate.
+3. Pipeline status/trigger with idempotency keys and bounded polling.
+4. Backup list/create/download safeguards before any cloud mutation.
+
+Catalog and Studio Pro extensibility remain separate adapters because they do not reduce native build/runtime dependency risk.

data/docs/en-US/platform-operations.md

@@ -0,0 +1,244 @@
+# Operations, lifecycle, and Marketplace
+
+## Diagnostics, benchmarks, and evolution
+
+```sh
+mxrb doctor .
+mxrb benchmark App.mpr --iterations 5 --json
+mxrb project inspect . --json
+mxrb upgrade --mendix 11.12.1 --target .
+mxrb upgrade --mendix 11.12.1 --target . --apply
+mxrb migrate plan .
+mxrb migrate check .
+```
+
+`doctor` checks the Ruby project, aggregators, MPR, and local toolchain.
+`benchmark` measures opening, semantic indexing, and validation. Upgrades are
+previews unless `--apply` is passed. Migration generates into a temporary area
+and compares that result with the current MPR; `check` fails on model drift.
+
+## Frontend migration and acceptance
+
+```sh
+mxrb frontend migrate App.mpr --json
+mxrb frontend migrate App.mpr --apply --json
+script/frontend_acceptance App.mpr -o frontend-round-trip.json
+script/frontend_acceptance App.mpr --mxbuild /path/to/mxbuild -o frontend.json
+script/frontend_acceptance App.mpr --mx /path/to/mx -o frontend-diagnostics.json
+script/frontend_lifecycle_acceptance --version 11.12.1 --mx /path/to/mx \
+  --mxbuild /path/to/mxbuild --strict-warnings -o frontend-lifecycle.json
+script/frontend_browser_acceptance --scenario examples/frontend-browser-scenario.json \
+  --url http://127.0.0.1:18080 --password-file /path/to/credentials.json \
+  --baseline examples/frontend-browser-baseline-11.12.1.json
+script/frontend_browser_acceptance --scenario examples/page-chain-browser-scenario.json \
+  --url http://127.0.0.1:18080 --password-file /path/to/credentials.json
+```
+
+`mxrb frontend migrate` is an immutable, fail-closed preview by default. For
+Mendix 10 and 11 it plans installed pluggable-widget schema updates, legacy
+layout-row weights, and design-property normalization from the package XML.
+`--apply` writes only a safe plan in one MPR transaction; unknown configured
+properties, an unsupported generation, or a unit changed after preview block
+the write. Neither preview nor apply invokes Mendix tooling.
+
+`script/frontend_acceptance` is the reproducible 10/11 gate. It validates the
+source and rebuilt MPRs, requires a compatible native preflight on both,
+exports to Ruby and rebuilds, compares model structure, and verifies complete
+asset inventories, bytes, SHA-256 checksums, and Marketplace provenance. The
+provenance boundary includes `.mxrb/marketplace.lock.json`, the package cache,
+and `.mxrb/marketplace-originals`; missing, changed, or unexpected files fail
+the gate. The accepted renderer matrix now covers Forms tables,
+`ListViewXPathSource`, listen-target object properties, structured page-variable
+mappings, and Combo-box enumerations. Its preflight baseline fell from 28 to 0
+findings on 10.24 and from 20 to 0 on 11.12.
+
+Without `--mxbuild`, the report scope is `round_trip` and `frontend_ready`
+remains unset. With `--mxbuild`, MxBuild is a read-only external oracle and the
+scope becomes `frontend`; it never generates, mutates, or repairs the project.
+The live oracle accepts success only when MxBuild exits zero and produces a
+non-empty MDA; a nonzero toolchain exit without reported model errors fails
+closed instead of being certified as a clean model.
+On August 4, 2026, the safe migration completed the accepted 10.24.0.73019 and
+11.12.1 matrix: source and rebuilt projects returned zero MxBuild errors and
+both reports set `frontend_ready` to `true`.
+
+`script/frontend_lifecycle_acceptance` creates an app exclusively through the
+CLI, generates its MPR, exports it to Ruby, changes Home and navigation, adds
+an entity, form, microflow, nanoflow, and asset, regenerates, exports again,
+and requires a structurally identical rebuild. On the official 10.24.0.73019
+and 11.12.1 matrix, source and rebuilt projects completed with zero errors,
+warnings, deprecations, or recommendations in `mx check`, plus zero MxBuild
+errors.
+
+`script/frontend_browser_acceptance` drives Chromium over local CDP,
+authenticates without placing the password on the command line, traverses
+pages, and compares deterministic structure, geometry, style, and ARIA-state
+snapshots. Browser exceptions, broken widgets, and the generic Runtime error
+dialog fail the gate. Baseline replacement requires explicit
+`--update-baseline`; normal runs are read-only comparisons. The gate signs out
+through `mx.logout()` so it remains repeatable under a trial license.
+
+`page-chain-browser-scenario.json` uses a `PageChainQa` app with `DirectOrder`,
+`ClientOrder`, and `HybridOrder`, created by the three `page --chain` values.
+It clicks `Refresh` on each page and also requires computed CSS — document
+margin, header gradient, and card background — so functional but unthemed HTML
+fails the gate.
+
+`--mx` runs the official read-only checker with warnings, deprecations, and
+best-practice recommendations enabled. It validates the checker's exit bitmask
+and compares normalized source/rebuilt signatures. The accepted 10.24 fixture
+has 0 errors, 173 package-owned warnings, 0 deprecations, and 2 Kafka
+recommendations; 11.12 has 0 errors, 10 package-owned warnings, 0 deprecations,
+and the same 2 recommendations. Source and rebuilt JSON are byte-identical in
+both generations, so these observable package diagnostics do not represent
+MXRB round-trip drift.
+
+## Official and community Mendix Marketplace
+
+MXRB uses the documented Mendix Marketplace Content API. Create a PAT with the
+`mx:marketplace-content:read` scope, then authenticate once:
+
+```sh
+cp .env.example .env
+# Set MXRB_MENDIX_PAT in .env; never commit the file.
+mxrb marketplace login --pat-file .env
+mxrb marketplace search "Community Commons"
+mxrb marketplace show 170
+mxrb marketplace versions 170 --mendix-version 11.12.1
+mxrb marketplace pull 170 --mpr MyApp.mpr
+mxrb marketplace pull 170@3.4.0 --mpr MyApp.mpr
+mxrb marketplace dependencies CommunityCommons --mpr MyApp.mpr
+mxrb marketplace dependencies CommunityCommons --mpr MyApp.mpr --apply
+mxrb marketplace dependencies CommunityCommons --mpr MyApp.mpr --apply-resolved
+mxrb marketplace update 170@3.5.0 --mpr MyApp.mpr
+mxrb marketplace update 170@3.5.0 --mpr MyApp.mpr --apply
+mxrb marketplace remove CommunityCommons --mpr MyApp.mpr
+mxrb marketplace remove CommunityCommons --mpr MyApp.mpr --apply
+mxrb marketplace pull github:mendix/CommunityCommons
+mxrb marketplace import ./CommunityCommons.mpk --mpr MyApp.mpr
+mxrb marketplace audit --target . --mendix-version 11.12.1
+mxrb marketplace list
+mxrb marketplace verify
+```
+
+The recommended login mode stores only the absolute `.env` path in
+`~/.config/mxrb/credentials` (or `$XDG_CONFIG_HOME/mxrb/credentials`). MXRB
+does not copy, move, chmod, or rewrite the referenced file; it reads it when an
+official Marketplace operation needs authentication. New scaffolds ignore
+`.env` and provide a secret-free `.env.example`.
+
+`mxrb marketplace login --store-pat` is an explicit managed-storage opt-in;
+the command displays its JSON destination and `0600` mode before prompting.
+`MXRB_MENDIX_PAT_FILE=/path/.env` works without persisting a reference. Run
+`mxrb marketplace login --help` for accepted formats and precedence.
+
+Official search includes public content and company-private content visible to
+the PAT owner. Filters include `--private`, `--public`, `--approved`, and
+`--published-since YYYY-MM-DD`. `show` exposes publisher, component type,
+support category, license, privacy, company approval, and latest release.
+`versions` exposes compatibility, release notes, and regular, vulnerable, or
+security-fix status including CVE/CWE identifiers.
+
+With `--mpr`, MXRB reads the package's `package.xml` and embedded
+`project.mpr`, then imports the complete module unit tree directly through
+Ruby/SQLite/BSON. It does not invoke `mx`, `mxcli`, Studio Pro, or the Model
+SDK. IDs are preserved, declared assets are installed transactionally, and
+the package cache plus module identity are recorded in the marketplace
+lockfile. Compatible official packages may be imported forward into the
+project's newer model version; local and GitHub imports still require an exact
+model-version match. Installing Atlas Core also connects its legacy Sass
+variables without replacing project customizations.
+
+Official `pull` is the default. It asks the API for the newest release compatible
+with the target MPR, follows the download URL returned by the API, and refuses a release marked
+vulnerable unless `--allow-vulnerable` is explicit. The lock records Content ID,
+Version ID, visibility, approval and security state; `audit` checks it for known
+vulnerabilities and updates. `github:` remains the public fallback, and `import`
+accepts a local MPK/ZIP. `login` validates the PAT before storing it outside the
+project with mode `0600`.
+
+The PAT is sent only to the exact official hosts `marketplace-api.mendix.com`
+and `marketplace.mendix.com`; redirects to any other host do not receive it.
+See the [Mendix Marketplace Content API](https://docs.mendix.com/apidocs-mxsdk/apidocs/content-api/).
+
+`marketplace dependencies` discovers unresolved qualified module references in
+the embedded package MPR, resolves them recursively through the official API,
+downloads each candidate, and accepts it only when the MPK itself proves the
+requested module identity. Host-owned project modules satisfy references
+without being mislabeled as Marketplace packages. The command previews by
+default; `--apply` requires a complete safe graph and installs leaf-first with
+rollback, while `--apply-resolved` is the explicit opt-in for a verified partial
+graph and still returns a blocked status for unresolved identities.
+
+Authenticated acceptance on August 4, 2026 imported Kafka 2.12.0 (Content ID
+105878) and resolved its official dependency graph on both 10.24.0.73019 and
+11.12.1. Both graphs imported DataWidgets 3.11.3 with Content ID 116540 and
+Version ID `e7b6d703-8e47-42f4-bb92-934e3601e71b`. The final authenticated
+Combo box is the independent official Widget/clientModule component 219304,
+version 2.9.0, Version ID `dce845f4-d051-4161-847c-016c01703caa`. Its install
+backs up and replaces the older 2.6.x Combo asset brought by Atlas Core
+(Content ID 117187); Atlas is the prior asset owner, not the Combo component.
+The 11.12 graph also includes Library Logging 1.13.0, Encryption 11.1.1,
+Mx Model Reflection 9.1.0, and Mendix Feedback Module 5.0.0 (Content ID
+205506). The API name index does not expose `FeedbackModule`, so MXRB uses the
+official component ID only as a discovery hint and still verifies the
+downloaded MPK name before accepting it.
+
+Both generations now pass the complete frontend acceptance gate with zero
+source and rebuilt preflight findings, structural equivalence, exact asset and
+Marketplace provenance, and zero MxBuild errors. The Ruby export/rebuild
+preserves the Marketplace lock, cached MPKs, originals, declared assets, and
+their checksums, so the rebuilt project retains package provenance instead of
+merely retaining widget bytes. MxBuild remains external validation only, never
+an MXRB implementation dependency.
+
+Official `update` and `remove` are safe previews unless `--apply` is explicit.
+Before mutation, MXRB checks the locked module and unit count against the cached
+package, scans every unit outside the module for references to IDs that would
+disappear, and refuses changed or missing package assets. An update must retain
+the module ID and any externally referenced unit IDs. Apply snapshots the MPR,
+v2 `mprcontents`, lock, caches, declared assets, and Atlas variables file; any
+failure restores that complete boundary. Shared assets are never removed while
+another locked package claims them.
+
+## Protocol connector audit
+
+`mxrb protocols` is a read-only audit of the IoT, industrial, and messaging
+connectors a project imported from the Marketplace. It never runs a protocol
+and never installs anything; it reports the public metadata the model exposes.
+
+```sh
+mxrb protocols App.mpr
+mxrb protocols App.mpr --json
+```
+
+Recognized connectors are listed with their module name, protocol, and
+Marketplace component id; unrecognized marketplace modules are listed
+separately. Recognition is by verified `AppStoreGuid`, so a module whose GUID
+is not confirmed from a real fixture or official metadata is reported as
+unrecognized rather than guessed.
+
+This protocol registry is a third catalog, distinct from the reusable Ruby
+modules of `mxrb module` and the official packages of `mxrb marketplace`.
+
+Verified public component ids currently cover MQTT, OPC-UA, Kafka, AMQP and
+WebSocket. Authenticated Content API queries and the official catalog search
+still provide no Modbus component, so it remains unregistered until an official
+component or real MPR fixture proves its identity. Public ids support planning;
+recognition inside an MPR still requires a verified `AppStoreGuid`.
+
+The Ruby builder can declare an installation request without writing an empty
+module or invented GUID:
+
+```ruby
+builder.connector :kafka, version: "2.12.0"
+plans = builder.connector_plans(adapter: Mxrb::Protocols.adapter(installer:, api:))
+plans.each { puts _1.changes }
+plans.each(&:apply!) # explicit authenticated Marketplace operation
+```
+
+`connector_plans` is preview-only without the adapter. A regular `build!` also
+fails closed while connector declarations are pending; connector content must
+be installed into a real MPR through the official Marketplace adapter first.
+Marketplace `Module` and `Service` entries may be resolved, while the downloaded
+MPK independently has to pass the module-package boundary checks.

data/docs/en-US/project-structure.md

@@ -0,0 +1,49 @@
+# Exported project structure
+
+[Português](../pt-BR/project-structure.md) · **English** · [Deutsch](../de-DE/project-structure.md)
+
+The Ruby tree produced by `mxrb export` separates app-wide policy, module
+behavior, preserved native units and filesystem assets:
+
+```text
+project.rb
+.mxrb/
+  native_units.json
+  native_units.rb
+  assets.json
+app/
+  security/security.rb
+  navigation/navigation.rb
+  design_system/design_system.rb
+modules/
+  ModuleName/
+    domain/
+    application/
+    presentation/
+    infrastructure/
+    security/
+theme/
+themesource/
+resources/
+widgets/
+javasource/
+javascriptsource/
+```
+
+`project.rb` is orchestration. Module files own model behavior. The native
+manifest preserves structures without a concise typed DSL. The asset manifest
+records relative paths, sizes and SHA-256 digests for every copied project
+asset.
+
+Reconstruction validates every asset path and digest, then writes only the
+manifest entries. Absolute paths, parent traversal, missing sources and
+checksum mismatches fail closed.
+
+The same tree supports all four normal workflows:
+
+- Ruby definition to a new Mendix project;
+- Ruby changes over an exported Mendix baseline;
+- Mendix project to editable Ruby;
+- Mendix export to Ruby and back to a structurally equivalent Mendix project.
+
+[Back to the documentation index](README.md)