mxrb 0.1.0

data/docs/pt-BR/native-runtime-quality-report.md

@@ -0,0 +1,73 @@
+# Relatório de qualidade do build e Runtime nativos
+
+Data: 5 de agosto de 2026.
+
+## Resultado confirmado
+
+- nenhuma etapa funcional chama `mx`, `mxbuild`, `mxcli`, Studio Pro ou Model SDK;
+- build limpo de 12 estágios e geração web passaram em 6.10.8 (39 páginas), 7.5.0 (45), 7.17.0 (66), 9.6.1.29396 (90), 10.24.0.73019 (cliente otimizado) e 11.12.1;
+- a matriz de round-trip passou em seis fixtures reais de 5.21.4 a 11.12.1: 1.506 units, 1.734 artefatos e 3.388 referências;
+- schemas/seeds auditados do compilador cobrem 6.x, 7.x, 9.x, 10.x e 11.x. 5.x e 8.x falham fechadas na compilação nativa; a Runtime exige o patch exato;
+- Data Grid 1 cobre database/XPath/microflow, pesquisa, ordenação, paginação, seleção e botões auditados. Data Grid 2 cobre XPath, colunas de atributo e ação create;
+- perfis web: Dojo em 6/7, híbrido Dojo/React em 9, clássico/otimizado conforme o projeto em 10 e React em 11;
+- a Projects API inventariou 130 apps. Três projetos Git reais (`MyFirstModule`, `LearnNow Trainning Management` e `SLATaskApp`) passaram validate → export → generate → validate → compare;
+- `MyFirstModule` foi regenerado como 11.12.1 exato sem builders proprietários. A Runtime sincronizou 655 operações, criou o administrador `mx` ativo, serviu shell React e login estilizado em `127.0.0.1:18080` e expôs as tabelas esperadas;
+- uma aplicação 10.24.0.73019 com cliente otimizado, criada do zero, passou no `mx check` e `mxbuild` oficiais, modelo/Java/Rollup/pacote portátil nativos, 460 operações de sincronização, probe de prontidão e HTTP 200;
+- QA autenticado em Chromium passou repetidamente em Home e Orders, com
+  snapshots DOM/layout/estilo/ARIA e screenshots determinísticos, zero erros de
+  console e baseline SHA-256 explícito;
+- `mxrb page new|generate|g Module.Page --chain ...` materializa MPRs válidos
+  para `page:microflow`, `page:nanoflow` e `page:nanoflow:microflow`; sem a
+  opção, o scaffold mínimo de página permanece inalterado;
+- `mxrb page templates` expõe a árvore starter/blank/dashboard/form-vertical;
+  `--template` combina os modelos com as chains, e dashboard/form-vertical
+  passaram em Runtime real com tema compilado e zero erros de console;
+- QA final: 1.039 exemplos, zero falhas, 100,00% de linhas (17.224/17.224), 100,00% de branches (6.811/6.811) e RuboCop limpo em 244 arquivos.
+
+## Correções do relatório de melhorias
+
+- geração seletiva de proxies Java para entidades, herança, enumerações e constantes usadas pelo Java customizado;
+- lowering da extensão oficial do Database Connector para Java actions do External Database Connector, inclusive `SELECT` seguro do query builder;
+- fontes OQL, flags herdadas de persistência, roles de demo user, system texts e storage/access rights exatos;
+- readiness estável do PostgreSQL, porta pública loopback (`--runtime-port`), senha administrativa por ambiente e criação do admin;
+- recursos de login autossuficientes, placeholders renderizados, cache busting, estilo e i18n;
+- hidratação do Atlas CSS, manifest e assets públicos; a homepage real do Team
+  Server agora renderiza grids, títulos e botões React acionáveis;
+- imports de página no modo developer carregam o token da sessão; o chunk
+  corrigido recebe hash de conteúdo e a autoimportação do Rspack compartilha o
+  token do entrypoint, eliminando a homepage branca obsoleta sem desabilitar cache;
+- o shell gerado fornece um adaptador limitado de `openForm` sobre `openForm2`,
+  para que handlers antigos em cache naveguem em vez de falhar silenciosamente
+  sem disparar request para a Runtime;
+- a Gallery React oficial agora renderiza dados XPath e microflow, templates de
+  item, seleção e valores string/numéricos formatados. O QA autenticado mostrou
+  título, descrição, `90 day(s)` e `49.95`; a Gallery vazia de Teachers
+  permaneceu presente na estrutura;
+- fontes nanoflow de lista/objeto e ações de botão agora compilam para os
+  contratos reais do cliente Mendix e programas de instruções referenciados por
+  função. O subconjunto auditado do grafo inclui decisões, caminhos de erro,
+  nanoflows aninhados, ações JavaScript e chamadas de microflow servidor; nós
+  não suportados falham fechado em vez de serem tratados como microflows;
+- o workspace PostgreSQL injeta a JDBC URL coerente e a opção de SSL no Runtime;
+  papéis de navegação em `CheckNothing`, modos de scroll, SidebarToggle e as
+  constantes de retorno de data sources de microflow seguem os contratos reais
+  observados no cliente 11.12.1;
+- cliques reais no navegador validaram Home → Courses → Add → Save. Formulários
+  DataView/TextBox por parâmetro renderizam e persistem valores; create passa o
+  GUID por `openForm2`, enquanto a autorização de commit/rollback deriva dos
+  module roles da página. O PostgreSQL confirmou os quatro valores de QA salvos;
+- proteção contra traversal em templates/imagens/ZIP, identificadores inseguros e symlinks nos inputs nativos;
+- comparação normaliza defaults booleanos ausentes do Runtime, restaurando round-trips legados exatos.
+
+## Limites explícitos
+
+1. Widgets Dojo além do Data Grid 1 permanecem listados em `web/mxrb-legacy-pages.json`; não são declarados renderizados.
+2. Data Grid 2 cobre o subconjunto auditado XPath/atributo/create. Gallery cobre
+   XPath/microflow e o subconjunto auditado do grafo nanoflow. Formatos de grafo
+   não suportados, referências ausentes, mapeamentos de parâmetros inseguros e
+   instruções cliente não traduzidas ainda falham fechado.
+3. As distribuições 6/7/9 instaladas têm bundles exatos, mas não launcher compatível. O launcher 11 exige Java 21 e não inicia 9 com segurança no Java 11. O `db up` legado falha fechado; boot exato é afirmado somente para 10.24.0.73019 e 11.12.1.
+4. A Runtime usa licença local trial/developer e emite o aviso esperado de limite de tempo.
+5. Build/Deploy/Pipelines/Backups em nuvem são verificações externas opcionais, nunca dependências do build/runtime nativo.
+
+Não existe fallback oculto para `mx`/`mxbuild`.

data/docs/pt-BR/oql-sql.md

@@ -0,0 +1,208 @@
+# OQL, visão SQL e banco local
+
+O MXRB só expõe OQL quando o modelo nativo realmente contém OQL. A descoberta
+abrange fontes OQL de datasets e consultas de view entities; um aplicativo sem
+OQL retorna uma coleção vazia e não recebe documentos de consulta artificiais.
+
+## Inspeção estática
+
+```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
+```
+
+A CLI fornece o mesmo resultado tipado:
+
+```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
+```
+
+A visão SQL é estritamente de leitura. Parâmetros como `$Customer` viram binds
+nomeados como `:Customer`; valores nunca são interpolados. Literais de texto e
+comentários permanecem opacos. Múltiplas instruções e operações OQL de escrita
+são recusadas.
+
+O SQL gerado tem confiança `logical`. As visões PostgreSQL e SQL Server usam a
+forma convencional de tabela `module$entity`; ANSI preserva `Module.Entity`.
+Os nomes físicos devem ser conferidos no banco criado pelo Runtime Mendix
+exato. Joins por caminho de associação são declarados não suportados enquanto
+os metadados de armazenamento do Runtime não puderem provar o join correto.
+
+## Análise dialect-aware
+
+`Oql::Analyzer` encontra padrões de custo e portabilidade na fonte original,
+preserva o fragmento para highlight e devolve sugestões para PostgreSQL, SQL
+Server e 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) }
+```
+
+As regras cobrem wildcard inicial, wildcard dos dois lados, busca por prefixo,
+`LOWER`/`UPPER`/`CAST` no `WHERE`, produto cartesiano e `SELECT *`. Findings
+são `hint`, `warning` ou `error`; `clean?` indica ausência de erros.
+
+O CLI analisa OQL nativo e fontes ad-hoc tanto OQL quanto SQL:
+
+```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
+```
+
+## Plano real e performance do banco
+
+A análise estática não prova qual caminho o otimizador escolherá. No workspace
+PostgreSQL materializado, o MXRB também consulta o planner real em JSON e cruza
+as relações do plano com `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
+```
+
+O modo padrão usa `EXPLAIN` e não executa a consulta. `--analyze` é explícito
+porque usa `EXPLAIN ANALYZE`; a consulta é executada com o papel read-only e
+inclui tempos e buffers. O relatório distingue scans sequenciais pequenos, que
+podem ser ótimos, de scans grandes; também sinaliza muitas linhas descartadas
+pelo filtro, estimativa de cardinalidade divergente, nested loops volumosos e
+sorts que foram para disco. Índices existentes são mostrados como evidência,
+mas o MXRB não inventa `CREATE INDEX` sem conhecer seletividade e workload.
+
+O workload cumulativo do PostgreSQL também pode ser inspecionado:
+
+```sh
+bundle exec mxrb db workload Shop.mpr --limit 50
+bundle exec mxrb db workload Shop.mpr --limit 50 --json
+bundle exec mxrb db workload Shop.mpr --save .mxrb/workload.json
+bundle exec mxrb db workload Shop.mpr --compare .mxrb/workload.json
+bundle exec mxrb db indexes Shop.mpr --limit 50
+```
+
+O workspace habilita `pg_stat_statements` e `track_io_timing`. O relatório
+ordena fingerprints por custo acumulado e analisa latência média, cache hit,
+I/O, blocos temporários e linhas por chamada. Estatísticas de tabelas revelam
+pressão de scans sequenciais; índices não únicos grandes e sem scans observados
+também são sinalizados. Como essas métricas são cumulativas desde o reset, uma
+remoção de índice nunca é sugerida sem confirmar janela e workload reais.
+O baseline permite comparar custo acumulado e latência entre execuções; o
+advisor cruza queries, filtros, estatísticas de tabelas e índices existentes.
+Ele retorna candidatos com evidência e confiança, além de sobreposições, mas
+não aplica DDL automaticamente.
+
+Para um deployment SQL Server, a conexão é explícita e usa `sqlcmd`:
+
+```sh
+export MXRB_SQLSERVER_PASSWORD='segredo'
+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
+bundle exec mxrb db workload Shop.mpr --engine sql_server \
+  --server db.example:1433 --database Shop --user mxrb_analyst --limit 50
+```
+
+O modo estimado usa `SHOWPLAN_XML`; `--analyze` usa `STATISTICS XML` e executa
+somente um `SELECT`/`WITH`. O parser detecta table/clustered scans grandes,
+nested loops volumosos, spills para tempdb, divergência de cardinalidade e
+hints de missing index. Esses hints permanecem hipóteses do otimizador, não
+DDL automático. A senha vai em `SQLCMDPASSWORD`, nunca em argv. O engine não é
+inferido do MPR porque pertence à configuração do deployment.
+
+## PostgreSQL local materializado
+
+O MPR contém o modelo da aplicação, não um snapshot dos dados. O Runtime Mendix
+é responsável pelo esquema do banco e por sincronizá-lo a partir do modelo. O
+MXRB pode compilar o Runtime portátil exato, iniciar um PostgreSQL isolado,
+permitir essa sincronização e expor acesso SQL:
+
+```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
+```
+
+Depois de alterar o MPR, recompile e sincronize preservando os dados:
+
+```sh
+bundle exec mxrb db sync Shop.mpr
+bundle exec mxrb db down Shop.mpr
+```
+
+`db down` para os containers, mas preserva o volume PostgreSQL. Um novo
+`db up` reutiliza o pacote em cache e os dados. A porta padrão é
+`127.0.0.1:55432` e pode ser alterada com `--port`.
+
+Para ferramentas locais, o mesmo workspace pode ser exposto como JSON HTTP:
+
+```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"}'
+```
+
+O corpo aceita exatamente um campo `sql` ou `oql`. OQL ad-hoc passa pelo
+tradutor PostgreSQL seguro; consultas parametrizadas e qualquer instrução que
+não seja um único `SELECT`/`WITH` são rejeitadas. A resposta inclui `rows`,
+`row_count`, `elapsed_ms`, avisos ou um erro estruturado. O servidor escuta
+somente em loopback, usa `mxrb_reader` e prepara o workspace por padrão;
+`--no-up` reutiliza um workspace já ativo.
+
+A limpeza permanente é deliberadamente explícita:
+
+```sh
+bundle exec mxrb db destroy Shop.mpr --yes
+```
+
+Ela remove apenas recursos com o rótulo de propriedade correspondente do MXRB.
+
+## Fronteira de segurança
+
+- O PostgreSQL só escuta na interface de loopback.
+- Cada caminho absoluto de MPR recebe containers, rede, volume e estado
+  separados.
+- Credenciais aleatórias ficam no diretório de estado XDG do usuário, fora do
+  repositório e com modo `0600`.
+- `db sql`, `db shell` e `db url` usam `mxrb_reader`, cujas transações e
+  configuração do papel são somente leitura.
+- `mxrb_reader` recebe `pg_read_all_stats` no workspace isolado para correlacionar
+  fingerprints do Runtime; isso não concede escrita em dados da aplicação.
+- `--write` seleciona explicitamente o papel proprietário do Runtime. Escritas
+  diretas podem violar invariantes Mendix e devem ser excepcionais.
+- O workspace PostgreSQL nunca aponta para banco remoto existente. A análise
+  SQL Server é uma conexão de deployment separada e explícita; use um login
+  somente leitura com permissão de SHOWPLAN. A senha fica em variável de
+  ambiente e keywords de mutação são rejeitadas, inclusive em CTEs.
+
+O toolchain Mendix exato e o daemon Docker precisam estar disponíveis.
+Para planos SQL Server, `sqlcmd` precisa estar instalado.
+Sincronizações de esquema podem alterar ou rejeitar dados existentes quando o
+modelo muda; faça backup de volumes locais valiosos antes de migrações de risco.
+
+Consulte a documentação oficial sobre
+[OQL](https://docs.mendix.com/refguide/oql/),
+[armazenamento de dados](https://docs.mendix.com/refguide/data-storage/) e
+[configuração do Runtime](https://docs.mendix.com/refguide/custom-settings/).

data/docs/pt-BR/platform-api-integration.md

@@ -0,0 +1,36 @@
+# Avaliação de integração das APIs Mendix
+
+Data: 1º de agosto de 2026. Fonte: índice oficial de [APIs e SDKs Mendix](https://docs.mendix.com/apidocs-mxsdk/).
+
+## Matriz de decisão
+
+| API ou SDK | Uso no MXRB | Decisão |
+| --- | --- | --- |
+| Projects API | listar apps acessíveis e metadados dos projetos | integrada em `team-server projects`; leitura por padrão |
+| App Repository API | informações do repositório, branches e commits | integrada na descoberta e clone do Team Server |
+| Marketplace Content API | descobrir e baixar módulos/widgets | integrada nas operações de Marketplace |
+| Build API | comparar artefato nativo do MXRB com build oficial em nuvem | verificação opcional; nunca dependência do build nativo |
+| Deploy API v4 | inventariar apps/ambientes antes da validação de release | adaptador somente leitura proposto; mutações exigem confirmação explícita |
+| Pipelines API | iniciar e observar pipeline CI/CD existente | adaptador opt-in proposto, com idempotência e consulta de estado |
+| Backups API v2 | listar/criar/baixar snapshots antes de deployment | adaptador de segurança proposto; restore/delete continuam explícitos |
+| Runtime API 11 | compilar Java e validar contratos do Runtime | contrato para proxies; é API Java, não substituto REST remoto |
+| Client e Pluggable Widget APIs | contratos Dojo/React/Data Grid | referência dos artefatos web gerados, não cliente HTTP |
+| Catalog APIs | registrar/consultar fontes governadas | plugin futuro; fora do núcleo build/runtime |
+| Model/Platform SDKs e extensibilidade do Studio Pro | modelagem remota ou extensão do Studio Pro | não obrigatórios; MXRB continua Ruby/SQLite/BSON independente |
+
+## Regras de integração
+
+- Chamadas remotas são explícitas; `generate`, `compile`, `validate` e `db up` nunca acessam a Mendix Cloud.
+- PATs/API keys vêm de arquivo protegido ou ambiente e nunca entram em relatórios, logs, projetos ou Git.
+- Leitura é o padrão. Build, deploy, pipeline, restore, membros e exclusões exigem comando próprio e confirmação proporcional ao impacto.
+- A Build API só funciona com apps na Mendix Cloud e usa API key da conta; não substitui o compilador nativo local.
+- APIs versionadas de Runtime/frontend são evidência de compatibilidade. O MXRB mantém schemas/seeds exatos e falha fechado sem contrato ou launcher compatível.
+
+## Ordem recomendada
+
+1. Listagem de branches/commits do App Repository no `team-server`.
+2. Inventário somente leitura do Deploy e gate opcional de comparação via Build.
+3. Estado/disparo de Pipelines com idempotência e polling limitado.
+4. Proteções de listar/criar/baixar Backups antes de mutação em nuvem.
+
+Catalog e extensibilidade do Studio Pro ficam em adaptadores separados, pois não reduzem o risco do núcleo nativo.

data/docs/pt-BR/platform-operations.md

@@ -0,0 +1,260 @@
+# Operação, lifecycle e Marketplace
+
+## Diagnóstico, benchmark e evolução
+
+```sh
+mxrb doctor .
+mxrb doctor . --json
+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` verifica o projeto Ruby, agregadores, MPR e toolchain disponível.
+`benchmark` mede abertura, construção do índice semântico e validação. Upgrade
+é preview por padrão; `--apply` altera somente a declaração de versão no
+`project.rb`. Migration gera o projeto em área temporária e compara o modelo
+resultante com o MPR atual; `check` retorna erro quando existe drift.
+
+## Migração e aceitação do frontend
+
+```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 /caminho/mxbuild -o frontend.json
+script/frontend_acceptance App.mpr --mx /caminho/mx -o frontend-diagnostics.json
+script/frontend_lifecycle_acceptance --version 11.12.1 --mx /caminho/mx \
+  --mxbuild /caminho/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 /caminho/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 /caminho/credentials.json
+```
+
+`mxrb frontend migrate` é uma prévia imutável e fail-closed por padrão. Para
+Mendix 10 e 11, planeja a atualização dos schemas dos pluggable widgets
+instalados, dos pesos legados de linhas de layout e das design properties a
+partir do XML do pacote. `--apply` grava somente um plano seguro em uma única
+transação no MPR; propriedades configuradas desconhecidas, geração não
+suportada ou unit alterada depois da prévia bloqueiam a escrita. Nem a prévia
+nem a aplicação executam ferramentas Mendix.
+
+`script/frontend_acceptance` é o gate reproduzível de 10/11. Ele valida os MPRs
+de origem e reconstruído, exige preflight nativo compatível em ambos, exporta
+para Ruby e reconstrói, compara a estrutura do modelo e verifica
+inventários completos de assets, bytes, SHA-256 e proveniência do Marketplace.
+A fronteira de proveniência inclui `.mxrb/marketplace.lock.json`, o cache de
+pacotes e `.mxrb/marketplace-originals`; arquivo ausente, alterado ou inesperado
+reprova o gate. A matriz aceita do renderer agora cobre tabelas de Forms,
+`ListViewXPathSource`, propriedades de objeto de listen target, mappings
+estruturados de variáveis de página e enumerações de Combo box. O baseline do
+preflight caiu de 28 para 0 achados no 10.24 e de 20 para 0 no 11.12.
+
+Sem `--mxbuild`, o relatório tem escopo `round_trip` e deixa `frontend_ready`
+sem valor. Com `--mxbuild`, o MxBuild atua como oráculo externo somente leitura
+e o escopo passa a `frontend`; ele nunca gera, altera ou repara o projeto.
+O oráculo ao vivo só aceita sucesso quando o MxBuild termina com status zero e
+produz um MDA não vazio; falha não zero da toolchain sem erros de modelo
+registrados falha fechada em vez de certificar um modelo limpo.
+Em 4 de agosto de 2026, a migração segura concluiu a matriz aceita 10.24.0.73019 e
+11.12.1: origem e reconstrução retornaram zero erros no MxBuild e os dois
+relatórios marcaram `frontend_ready` como `true`.
+
+`script/frontend_lifecycle_acceptance` cria um app exclusivamente pela CLI,
+gera o MPR, exporta-o para Ruby, altera a Home e a navegação, adiciona entidade,
+formulário, microflow, nanoflow e asset, gera novamente, exporta uma segunda vez
+e exige reconstrução estruturalmente idêntica. Na matriz oficial 10.24.0.73019
+e 11.12.1, origem e reconstrução concluíram com zero erros, warnings,
+depreciações e recomendações no `mx check`, além de zero erros no MxBuild.
+
+`script/frontend_browser_acceptance` controla Chromium por CDP local, autentica
+sem colocar senha na linha de comando, percorre páginas e compara snapshots
+determinísticos de estrutura, geometria, estilos e estado ARIA. Exceções do
+navegador, widgets quebrados e o diálogo genérico de erro do Runtime reprovam o
+gate. `--update-baseline` é explícito; execuções normais apenas comparam. O gate
+faz logout pela API `mx.logout()` e pode ser repetido sob licença trial.
+
+O cenário `page-chain-browser-scenario.json` usa uma app `PageChainQa` com
+`DirectOrder`, `ClientOrder` e `HybridOrder`, criadas pelos três valores de
+`page --chain`. Ele aciona `Refresh` em cada página e exige também CSS
+computado — margem do documento, gradiente do cabeçalho e fundo dos cards —,
+portanto HTML funcional sem tema reprova o gate.
+
+`--mx` executa o checker oficial somente leitura com warnings, depreciações e
+recomendações de boas práticas. O gate valida o bitmask de saída e compara as
+assinaturas normalizadas de origem e reconstrução. A fixture 10.24 aceita tem
+0 erros, 173 warnings dos pacotes, 0 depreciações e 2 recomendações do Kafka;
+a 11.12 tem 0 erros, 10 warnings dos pacotes, 0 depreciações e as mesmas 2
+recomendações. Os JSONs de origem e reconstrução são idênticos byte a byte nas
+duas gerações; esses diagnósticos observáveis dos pacotes não são drift do MXRB.
+
+## Marketplace Mendix oficial e comunitário
+
+O MXRB usa a Marketplace Content API documentada pela Mendix. Crie um PAT com
+o escopo `mx:marketplace-content:read` e autentique uma vez:
+
+```sh
+cp .env.example .env
+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 VetClinic.mpr
+mxrb marketplace pull 170@3.4.0 --mpr VetClinic.mpr
+mxrb marketplace dependencies CommunityCommons --mpr VetClinic.mpr
+mxrb marketplace dependencies CommunityCommons --mpr VetClinic.mpr --apply
+mxrb marketplace dependencies CommunityCommons --mpr VetClinic.mpr --apply-resolved
+mxrb marketplace update 170@3.5.0 --mpr VetClinic.mpr
+mxrb marketplace update 170@3.5.0 --mpr VetClinic.mpr --apply
+mxrb marketplace remove CommunityCommons --mpr VetClinic.mpr
+mxrb marketplace remove CommunityCommons --mpr VetClinic.mpr --apply
+mxrb marketplace pull github:mendix/CommunityCommons
+mxrb marketplace import ./CommunityCommons.mpk --mpr VetClinic.mpr
+mxrb marketplace audit --target . --mendix-version 11.12.1
+mxrb marketplace list
+mxrb marketplace verify
+```
+
+Busca oficial inclui conteúdo público e conteúdo privado da empresa visível ao
+dono do PAT. Os filtros incluem `--private`, `--public`, `--approved` e
+`--published-since AAAA-MM-DD`. `show` apresenta publicador, tipo, suporte,
+licença, privacidade e aprovação. `versions` apresenta compatibilidade, release
+notes e estados `Regular`, `Vulnerable` e `SecurityFix`, incluindo CVE/CWE.
+
+`pull` oficial é o padrão: seleciona pela API a versão mais recente compatível
+com o MPR, usa a URL de download retornada pela API e bloqueia versões vulneráveis, salvo uso explícito
+de `--allow-vulnerable`. `github:` continua como fallback e `import` aceita um
+MPK local. Com `--mpr`, o MXRB lê `package.xml` e o `project.mpr` interno, importa
+a árvore completa de units diretamente via Ruby/SQLite/BSON e instala os
+assets declarados. Não executa `mx`, `mxcli`, Studio Pro nem Model SDK. A
+operação preserva IDs, usa transação, restaura assets em falhas e recusa módulo
+duplicado. Pacotes oficiais compatíveis podem avançar para a versão mais nova
+do modelo do projeto; imports locais/GitHub continuam exigindo versão idêntica.
+Quando Atlas Core é instalado, o MXRB conecta suas variáveis Sass legadas sem
+sobrescrever as customizações do projeto.
+
+O pacote fica em `.mxrb/marketplace/` e versão, origem, Content ID, Version ID,
+estado de segurança, SHA-256, module ID, units, MPR e assets ficam registrados
+em `.mxrb/marketplace.lock.json`. `audit` consulta atualizações e vulnerabilidades.
+`verify` confere simultaneamente cache, presença do módulo no MPR e assets.
+Sem `--mpr`, o comportamento legado continua disponível para extrair arquivos
+ZIP de repositórios Ruby-first.
+`GITHUB_TOKEN` é opcional para elevar o limite da API pública.
+
+```sh
+cp .env.example .env
+# edite .env e defina MXRB_MENDIX_PAT sem versionar o arquivo
+mxrb marketplace login --pat-file .env
+```
+
+Por padrão recomendado, o login valida o PAT e salva **somente o caminho
+absoluto** do `.env` em `~/.config/mxrb/credentials` (ou
+`$XDG_CONFIG_HOME/mxrb/credentials`). O MXRB não copia, move, altera permissões
+nem reescreve o arquivo apontado; ele o lê quando uma operação oficial precisa
+autenticar. Scaffolds novos já ignoram `.env` e geram `.env.example` sem segredo.
+
+Quem preferir armazenamento gerenciado pode executar
+`mxrb marketplace login --store-pat`. Antes de pedir o PAT, o comando informa
+que gravará JSON no arquivo global com permissão `0600`. Também é possível usar
+`MXRB_MENDIX_PAT_FILE=/caminho/.env` sem persistir configuração. Consulte
+`mxrb marketplace login --help` para os formatos e precedência.
+
+O token só é enviado aos hosts oficiais exatos
+`marketplace-api.mendix.com` e `marketplace.mendix.com`; ele é removido em
+redirects para qualquer outro host. Consulte a
+[Marketplace Content API](https://docs.mendix.com/apidocs-mxsdk/apidocs/content-api/).
+
+`marketplace dependencies` descobre referências qualificadas não resolvidas no
+MPR interno do pacote, resolve o grafo recursivamente pela API oficial, baixa
+cada candidato e só o aceita quando o próprio MPK comprova a identidade do
+módulo solicitado. Módulos pertencentes ao projeto satisfazem referências sem
+serem rotulados como pacotes do Marketplace. O padrão é preview; `--apply`
+exige grafo completo e seguro, instala folhas primeiro e faz rollback, enquanto
+`--apply-resolved` é a opção explícita para aplicar apenas a parte comprovada e
+ainda retorna estado bloqueado para identidades não resolvidas.
+
+Em 4 de agosto de 2026, a aceitação autenticada importou Kafka 2.12.0 (Content
+ID 105878) e resolveu o grafo oficial em 10.24.0.73019 e 11.12.1. Os dois grafos
+importaram DataWidgets 3.11.3 com Content ID 116540 e Version ID
+`e7b6d703-8e47-42f4-bb92-934e3601e71b`. O Combo box autenticado final é o
+componente oficial independente Widget/clientModule 219304, versão 2.9.0,
+Version ID `dce845f4-d051-4161-847c-016c01703caa`. Sua instalação faz backup e
+substitui o asset Combo 2.6.x anterior trazido pelo Atlas Core (Content ID
+117187); o Atlas é o proprietário anterior do asset, não o componente Combo.
+O grafo 11.12 também inclui Library Logging 1.13.0, Encryption 11.1.1, Mx Model
+Reflection 9.1.0 e Mendix Feedback Module 5.0.0 (Content ID 205506). Como o
+índice por nome da API não expõe `FeedbackModule`, o MXRB usa o ID oficial
+somente como dica de descoberta e ainda exige que o MPK baixado prove o nome
+interno.
+
+As duas gerações agora passam no gate completo de aceitação do frontend com
+zero achados no preflight da origem e da reconstrução, equivalência estrutural,
+assets e proveniência do Marketplace exatos e zero erros no MxBuild. O
+export/rebuild Ruby preserva o lock do Marketplace, MPKs em cache, originais,
+assets declarados e seus checksums; assim, o projeto reconstruído mantém a proveniência dos pacotes,
+e não apenas os bytes dos widgets. A trilha segura de migração e os oráculos
+externos MxBuild/`mx check` estão concluídos na matriz suportada. Essas
+ferramentas continuam sendo apenas validação externa, nunca dependências da
+implementação MXRB.
+
+`update` e `remove` oficiais são prévias seguras sem `--apply`. Antes de
+alterar o projeto, o MXRB compara módulo e contagem de units do lock com o
+pacote em cache, varre todas as units externas em busca de referências a IDs
+que desapareceriam e recusa assets alterados ou ausentes. Um update precisa
+preservar o ID do módulo e todo ID referenciado externamente. Ao aplicar, o MXRB
+protege MPR, `mprcontents` v2, lock, caches, assets declarados e arquivo de
+variáveis do Atlas; qualquer falha restaura toda essa fronteira. Assets
+compartilhados não são removidos enquanto outro pacote no lock os declarar.
+
+Há dois marketplaces distintos: `mxrb module search/add` instala módulos Ruby
+reutilizáveis do ecossistema MXRB; `mxrb marketplace ...` instala pacotes
+Mendix oficiais/comunitários.
+
+## Auditoria de conectores de protocolo
+
+`mxrb protocols` é uma auditoria somente leitura dos conectores de IoT,
+industriais e de mensageria que um projeto importou do Marketplace. Ele nunca
+executa um protocolo e nunca instala nada; apenas relata os metadados públicos
+que o modelo expõe.
+
+```sh
+mxrb protocols App.mpr
+mxrb protocols App.mpr --json
+```
+
+Os conectores reconhecidos aparecem com nome do módulo, protocolo e id do
+componente no Marketplace; os módulos de marketplace não reconhecidos são
+listados à parte. O reconhecimento é por `AppStoreGuid` verificado, então um
+módulo cujo GUID não foi confirmado em fixture real ou metadado oficial é
+relatado como não reconhecido, nunca inferido.
+
+Este registro de protocolos é um terceiro catálogo, distinto dos módulos Ruby
+reutilizáveis de `mxrb module` e dos pacotes oficiais de `mxrb marketplace`.
+
+Os ids públicos verificados atualmente cobrem MQTT, OPC-UA, Kafka, AMQP e
+WebSocket. Consultas autenticadas à Content API e ao catálogo oficial ainda não
+retornam componente Modbus; por isso ele continua sem cadastro até que um
+componente oficial ou uma fixture MPR real comprove sua identidade. O id
+público serve para planejamento; o reconhecimento dentro de um MPR ainda exige
+`AppStoreGuid` verificado.
+
+O builder Ruby pode declarar a intenção de instalação sem escrever módulo vazio
+nem GUID inventado:
+
+```ruby
+builder.connector :kafka, version: "2.12.0"
+planos = builder.connector_plans(adapter: Mxrb::Protocols.adapter(installer:, api:))
+planos.each { puts _1.changes }
+planos.each(&:apply!) # operação autenticada e explícita no Marketplace
+```
+
+Sem o adapter, `connector_plans` é somente prévia. `build!` também falha fechado
+enquanto houver declarações pendentes: o conteúdo real deve ser instalado no
+MPR pelo adapter oficial. Entradas `Module` e `Service` podem ser resolvidas,
+mas o MPK baixado ainda precisa passar independentemente pelas validações de
+fronteira de pacote de módulo.

data/docs/pt-BR/project-structure.md

@@ -0,0 +1,32 @@
+# Estrutura do projeto exportado
+
+**Português** · [English](../en-US/project-structure.md) · [Deutsch](../de-DE/project-structure.md)
+
+A árvore produzida por `mxrb export` separa políticas globais, comportamento
+dos módulos, unidades nativas preservadas e assets:
+
+```text
+project.rb
+.mxrb/{native_units.json,native_units.rb,assets.json}
+app/{security,navigation,design_system}/
+modules/NomeDoModulo/{domain,application,presentation,infrastructure,security}/
+theme/
+themesource/
+resources/
+widgets/
+javasource/
+javascriptsource/
+```
+
+`project.rb` orquestra o carregamento. Os módulos contêm o comportamento. O
+manifesto nativo preserva estruturas ainda sem DSL concisa; o manifesto de
+assets registra caminho relativo, tamanho e SHA-256 de cada arquivo.
+
+Na reconstrução, caminhos absolutos, traversal com `..`, arquivos ausentes e
+checksums divergentes falham de forma segura. Somente entradas declaradas no
+manifesto são gravadas.
+
+A estrutura suporta Ruby para um Mendix novo, Ruby sobre baseline exportado,
+Mendix para Ruby editável e Mendix → Ruby → Mendix estruturalmente equivalente.
+
+[Voltar ao índice](README.md)