feat: Add initial documentation and architecture for EntityAssistReactive module

- Created README.md to outline project purpose, quick start, and contributing guidelines.
- Established RULES.md to define documentation-first workflow, scope, and selected stacks.
- Introduced PROMPT_REFERENCE.md to summarize selections and documentation loop for AI assistance.
- Added architecture documentation including C4 diagrams and ERD for EntityAssistReactive.
- Documented data flow, threat model, and dependency integration in architecture overview.
- Implemented sequence diagrams for entity persistence and query operations.
- Updated rules submodule reference for consistency.

Author: GedMarc

.env.example

@@ -0,0 +1,18 @@
+# Database connections are configured in GuicedEE DatabaseModule implementations
+# (see src/test/java/com/test/EntityAssistReactiveDBModule.java for an example).
+# This file only captures optional toggles and CI secrets.
+
+ENVIRONMENT=dev
+PORT=8080
+TRACING_ENABLED=false
+ENABLE_DEBUG_LOGS=false
+
+TEST_DB_CONTAINER_IMAGE=postgres:16
+SKIP_INTEGRATION_TESTS=true
+
+SONA_USERNAME=
+SONA_PASSWORD=
+GPG_PRIVATE_KEY=
+GPG_PASSPHRASE=
+GITHUB_ACTOR=
+GITHUB_TOKEN=

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "rules"]
+	path = rules
+	url = https://github.com/GuicedEE/ai-rules.git

GLOSSARY.md

@@ -0,0 +1,26 @@
+# EntityAssistReactive Glossary (Topic-First)
+
+## Precedence Policy
+1. Topic glossaries define canonical language. When a term exists in one of the selected glossaries, reference that entry instead of redefining it.
+2. This host glossary acts as an index + alignment guide for CRTP-based persistence discussions. Only EntityAssist-specific terms are defined locally.
+3. If a future topic is added (e.g., Angular or WebAwesome), link its glossary here and update RULES.md accordingly.
+
+## Selected Topic Glossaries
+- [GuicedEE Stack](rules/generative/backend/guicedee/GLOSSARY.md)
+- [Hibernate Reactive 7](rules/generative/backend/hibernate/GLOSSARY.md)
+- [Lombok](rules/generative/backend/lombok/GLOSSARY.md)
+- [Java LTS](rules/generative/language/java/GLOSSARY.md)
+- [GitHub Actions](rules/generative/platform/ci-cd/providers/github-actions.md)
+
+## EntityAssistReactive Terms
+
+| Term | Definition |
+| --- | --- |
+| **CRTP Entity** | A domain type that extends `RootEntity`/`BaseEntity` and feeds its own type arguments to retain fluent, type-safe methods. The CRTP strategy is mandatory for this repository; @Builder variants are disallowed. |
+| **Query Builder Root** | The class hierarchy under `com.entityassist.querybuilder.builders.*` that composes Hibernate Criteria queries with Mutiny sessions. Builders may run in stateful or stateless modes and must be provisioned through `IGuiceContext`. |
+| **Mutiny Session Boundary** | The trust boundary between application code and Hibernate Reactive sessions (`Mutiny.Session` or `Mutiny.StatelessSession`). All persistence operations cross this boundary; instrumentation and tracing must hook here. |
+| **EntityAssist Module** | The Java module `com.entityassist` exported by `module-info.java`. Hosts must declare `requires transitive com.entityassist` and follow the `opens` guidance documented in RULES.md. |
+| **Glossary Alignment Loop** | The requirement for every doc (PACT, RULES, GUIDES, IMPLEMENTATION) to link back to this glossary so terminology remains synchronized with topic glossaries. |
+
+## Unknowns to Clarify
+- Domain-specific entities (tables, schemas, column names) are not yet published in this repository; ERD diagrams document the abstract entity/query-builder relationship until modules ship concrete models.

GUIDES.md

@@ -0,0 +1,40 @@
+# EntityAssistReactive GUIDES
+
+This file explains how to apply the rules in practical workflows. Each section links to the topic references defined in `RULES.md`, the glossary, and the Stage 1 diagrams.
+
+## 1. Creating CRTP Entities & Builders
+1. Review `docs/architecture/sequence-persist-flow.md` to understand the runtime path.
+2. Define your entity by extending `RootEntity` or `BaseEntity` with the CRTP signature. Keep fields annotated with JPA + Bean Validation.
+3. Implement a matching `QueryBuilder` that extends `com.entityassist.querybuilder.QueryBuilder` (or `QueryBuilderRoot` for advanced cases) and injects via `IGuiceContext`.
+4. Add Guice bindings for the builder in the host service module per `rules/generative/backend/guicedee/functions/guiced-injection-rules.md`.
+5. Update `module-info.java` exports/opens if new packages are introduced, and document them in `IMPLEMENTATION.md`.
+6. Builder helper methods (`persist`, `update`, `delete`) always yield a `Uni<J>` containing the entity (never `null`) and simply propagate Hibernate Reactive exceptions—compose them with Mutiny error handling rather than wrapping inside the builder.
+
+## 2. Configuring Database Modules / Drivers
+1. Database connections are wired through GuicedEE `DatabaseModule` implementations annotated with `@EntityManager`. See `src/test/java/com/test/EntityAssistReactiveDBModule.java` for a Postgres Testcontainers example.
+2. Override `getConnectionBaseInfo` to supply host, port, credentials, and `setReactive(true)`; `getEntityManager()` in `QueryBuilderRoot` simply returns the Mutiny session injected via this module.
+3. To change drivers, follow `rules/generative/backend/vertx/README.md` plus the driver-specific template (e.g., `rules/generative/backend/vertx/vertx-5-postgres-client.md`) and adjust your `ConnectionBaseInfo` implementation accordingly.
+4. Record the driver choice in `docs/PROMPT_REFERENCE.md` and update ERD/diagrams if new capabilities (clustered writes, sharding) are introduced.
+
+## 3. Managing Mutiny Sessions
+1. Obtain sessions from `IGuiceContext`-managed factories; never instantiate `Mutiny.SessionFactory` manually.
+2. For read/write flows, mirror `docs/architecture/sequence-query-flow.md` to ensure `select()` is invoked before query execution.
+3. Cache hints (set via `QueryBuilder`) must align with the Hibernate Reactive rules in `rules/generative/backend/hibernate/README.md`.
+4. Any time new cache regions or transaction strategies are introduced, create a corresponding subsection in `IMPLEMENTATION.md` and reference the relevant guide.
+
+## 4. Environment Configuration
+- Use `.env.example` as the canonical reference for local `.env` creation.
+- Database keys: `DB_URL`, `DB_USER`, `DB_PASS`, `DB_POOL_SIZE`, `VERTX_DB_DRIVER`. Override per environment using Terraform/secret managers as described in `rules/generative/platform/secrets-config/env-variables.md`.
+- CI/CD secrets: `SONA_USERNAME`, `SONA_PASSWORD`, `GPG_PRIVATE_KEY`, `GPG_PASSPHRASE`, `GITHUB_TOKEN`. Map these to GitHub Actions environment secrets before running the workflow.
+
+## 5. Running + Testing
+1. `mvn -B verify` is the baseline command locally and in GitHub Actions (`.github/workflows/maven-publish.yml`).
+2. For integration tests, provide `TEST_DB_CONTAINER_IMAGE` and `SKIP_INTEGRATION_TESTS=false` in `.env` so Testcontainers can use the correct driver.
+3. The test JPMS module (`src/test/java/module-info.java`) shows the required `requires`/`opens` clauses for `module entity.assist.test`; new tests must extend this pattern so Hibernate Reactive, Guice, and JUnit can reflectively access entities.
+4. The Maven Surefire plugin passes `--add-reads org.hibernate.orm.core=entity.assist.test --add-reads org.jboss.logging=org.hibernate.reactive`. Preserve (or expand) those flags whenever you create new test runners/profiles so JPMS constraints are satisfied.
+
+## 6. Documentation Loop
+- Before proposing code changes, load `PACT.md`, `GLOSSARY.md`, `docs/PROMPT_REFERENCE.md`, and these guides.
+- After implementing a guide, capture the change in `IMPLEMENTATION.md` with links back to diagrams/guides to keep the Pact → Rules → Guides → Implementation chain intact.
+- Ensure consuming projects add the Hibernate annotation processor (`org.hibernate.orm:hibernate-processor`) to their `maven-compiler-plugin` (or equivalent) alongside Lombok so CRTP entities generate metadata correctly. This repository already models the configuration in `pom.xml`; mirror it before expecting builders to compile.
+- All consuming JPMS modules must include the necessary `--add-reads` arguments (`org.jboss.logging=org.hibernate.reactive`, `org.hibernate.orm.core=<your.module.name>`) and `opens` clauses so Hibernate Reactive can access entity packages. See `module-info.java` in test sources for an example mapping.

IMPLEMENTATION.md

@@ -0,0 +1,66 @@
+# EntityAssistReactive IMPLEMENTATION
+
+This document records the current state of the repository and links every implemented concern back to the rules, guides, and diagrams.
+
+## 1. Module Inventory
+| Path | Purpose | Notes |
+| --- | --- | --- |
+| `src/main/java/com/entityassist/RootEntity.java` | Base CRTP entity with persistence helpers | Uses Mutiny sessions + validation; referenced in `docs/architecture/c4-component-entityassist.md`. |
+| `src/main/java/com/entityassist/BaseEntity.java` | Extends `DefaultEntity` for richer behavior | Maintains CRTP signature and logging helpers. |
+| `src/main/java/com/entityassist/querybuilder/QueryBuilder.java` | Fluent criteria builder | Implements caching, joins, select/delete logic. |
+| `src/main/java/com/entityassist/querybuilder/builders/QueryBuilderRoot.java` | Lower-level criteria utilities | Manages `CriteriaBuilder`, delete/update statements, stateless sessions. |
+| `src/main/java/com/entityassist/converters/*.java` | Attribute converters | Align with ERD serialization to reactive SQL tables. |
+| `src/main/java/com/entityassist/services/**` | Service contracts | Define `IRootEntity`, `IQueryBuilder`, etc., ensuring fluent APIs are consistent. |
+| `module-info.java` | JPMS declarations | Requires transitive GuicedEE persistence, Hibernate Reactive, Vert.x SQL client. |
+
+## 2. Documentation Links
+- Architecture diagrams: `docs/architecture/README.md` (C4, sequences, ERD).
+- Rules + Guides: `RULES.md`, `GUIDES.md` (Stage 2), `GLOSSARY.md`.
+- Prompt coordination: `docs/PROMPT_REFERENCE.md` defines the stacks that future prompts must load.
+
+## 3. Reactive Flow Summary
+1. Service code instantiates or injects a CRTP entity (`RootEntity` derivative).
+2. `entity.builder(session)` retrieves a Guice-provisioned `QueryBuilder` bound to the Mutiny session (stateful or stateless).
+3. Builders configure joins, filters, cache hints, and then execute via Mutiny, producing `Uni<T>` results. These helpers never return `null`; any Hibernate exceptions bubble through the `Uni` so callers can handle them.
+4. Vert.x reactive drivers transport SQL commands; driver selection is tracked in `docs/PROMPT_REFERENCE.md` and `README.md` rather than environment variables.
+5. GitHub Actions (`.github/workflows/maven-publish.yml`) runs Maven verify/publish when secrets are present.
+
+## 4. Environment & CI Integration
+- `.env.example` only stores optional toggles and CI secrets because database credentials are injected via GuicedEE `DatabaseModule` overrides.
+- GitHub Actions inherits secrets defined in repository settings; refer to `rules/generative/platform/ci-cd/providers/github-actions.md`.
+- GPG/Sonatype credentials must be present before running the publish workflow; otherwise, builds stay in verify-only mode.
+
+## 5. Pending/Next Steps
+- Stage 3 will extend this document with implementation evidence (e.g., concrete bounded contexts, repositories using this library, diagrams per new modules).
+- When new features (multi-tenant patterns, custom drivers) are added, append sections referencing updated diagrams and guides.
+
+## 6. Stage 3 Implementation Plan (No Code)
+
+### 6.1 Scaffolding & Module Map
+- **Core module (`src/main/java/com/entityassist/**`)** — Already contains CRTP entities, query builders, converters, and service interfaces. Stage 4 tasks should map directly to these packages (e.g., add domain-specific entities under `com.entityassist.services.entities` or new builders under `com.entityassist.querybuilder.builders`).
+- **JPMS descriptor (`src/main/java/module-info.java`)** — Any new exports/opens must be recorded here and mirrored in `docs/architecture/c4-component-entityassist.md`.
+- **Database module examples (`src/test/java/com/test/EntityAssistReactiveDBModule.java`)** — Use this pattern to scaffold production `@EntityManager` modules in host services; wiring lives outside this repo but follows the same GuicedEE factory contract.
+- **Docs tree (`docs/architecture`, `RULES.md`, `GUIDES.md`)** — Stage 4 code updates must reference these artifacts when introducing new flows or terminology to keep the documentation loop closed.
+- **Test module (`src/test/java/module-info.java`)** — Shows the required `requires`/`opens` clauses for the JPMS test module (`module entity.assist.test`) plus the `provides` entry for `IGuiceModule`. Mirror this structure (including `opens com.test ... org.hibernate.orm.core`) when creating additional tests to keep reflective access working.
+
+### 6.2 Build & Annotation Processor Wiring
+- `pom.xml` already wires `maven-compiler-plugin` with Lombok (1.18.40) and Hibernate processor (`${maven.hibernate.version}`) plus explicit `--add-reads` arguments. Stage 4 changes must reuse this configuration; new processors should be added to the same plugin block and documented in `RULES.md`.
+- `maven-surefire-plugin` propagates JPMS flags via `<argLine>--add-reads org.hibernate.orm.core=entity.assist.test --add-reads org.jboss.logging=org.hibernate.reactive</argLine>`. Future test runners or profiles must keep these arguments (or their equivalents) so Hibernate Reactive can access the test module.
+- `flatten-maven-plugin` and `copy-rename-maven-plugin` are present; confirm before release whether they require configuration updates for new modules.
+- Dependencies rely on the GuicedEE BOM (`dependencyManagement`). Any new dependency must align with the BOM versions to avoid drift; document additions in `GUIDES.md` before editing the POM.
+
+### 6.3 CI Workflow & Validation
+- `.github/workflows/maven-publish.yml` delegates to `GuicedEE/Workflows/.github/workflows/projects.yml@master`. Stage 4 tasks should anticipate the existing inputs (e.g., `centralRelease`, `publishToCentral`) and note required secrets (USERNAME, USER_TOKEN, SONA_*, GPG_*).
+- Validation path: `mvn -B verify` locally and in CI; for reactive DB flows include Testcontainers-based tests with `TEST_DB_CONTAINER_IMAGE`. Add any new workflow requirements (additional jobs, linting) by extending the README + RULES before altering YAML.
+
+### 6.4 Environment & Config Plan
+- Database connections remain in GuicedEE `DatabaseModule` overrides (see Section 6.1). Future implementation work should deliver production-ready modules (per environment) and update GUIDES with credential source (Secret Manager, Vault, etc.).
+- `.env` usage is limited to toggles/secrets listed in `.env.example`; Stage 4 tasks must note additional keys there and in `rules/generative/platform/secrets-config/env-variables.md`.
+- Document how environment stacks feed into CI (e.g., GitHub Environments for release vs. snapshot) before changing workflows.
+
+### 6.5 Rollout Plan, Risks, and Validation Approach
+- **Phase 1 (Foundation)** — Introduce any new CRTP entities/builders plus DatabaseModule overrides in host services; validate with integration tests using Mutiny sessions and Testcontainers. Update diagrams if module boundaries change.
+- **Phase 2 (Feature rollout)** — Wire services to the new builders, ensure JPMS requirements are satisfied (add `opens`/`requires`), and document the flows in `GUIDES.md` + `IMPLEMENTATION.md`.
+- **Phase 3 (Release readiness)** — Confirm CI secrets, verify `mvn -B verify` + publishing workflow, and capture release notes referencing the documentation chain.
+- **Risks:** JPMS `--add-reads` errors if new modules are not declared; mismatched driver configuration if DatabaseModule overrides are inconsistent; CI failures when secrets are missing; documentation drift if diagrams are not updated alongside code.
+- **Validation:** For each phase, tie acceptance back to Stage 1/2 artifacts—e.g., confirm new features align with the ERD and sequence diagrams, ensure RULES coverage for additional stacks, and record proof in `IMPLEMENTATION.md`.

PACT.md

@@ -0,0 +1,56 @@
+---
+version: 2.0
+date: 2025-11-15
+title: Entity Assist Reactive Collaboration Pact
+project: EntityAssistReactive
+authors: [Entity Assist Maintainers, Contributors, Codex]
+---
+
+# 🤝 Entity Assist Reactive Pact (v2)
+*(Human × Codex — Documentation-First Edition)*
+
+## 1. Purpose
+
+EntityAssistReactive is a CRTP-first persistence library that injects fluent query builders into GuicedEE services on Vert.x 5 and Hibernate Reactive 7, delegating persistence to whichever Vert.x reactive database driver a host selects (PostgreSQL via vertx-pg-client by default). This pact captures the shared culture required to keep that stack coherent: documentation precedes code, terminology routes through the selected glossaries, and every artifact links forward (Pact → Rules → Guides → Implementation) so reactive schema work never drifts from architectural intent.
+
+## 2. Principles
+
+- **Continuity:** Stage-gated artifacts persist and evolve; nothing is overwritten without a forward-only rationale.
+- **Finesse:** Docs explain why each reactive decision exists (Mutiny session management, module boundaries, etc.).
+- **Non-Transactional Flow:** Prompts are “on-call runbooks” for the CRTP stack, not one-off answers.
+- **Closing Loops:** Each deliverable links to its upstream rules submodule entry and downstream implementation evidence.
+
+## 3. Structure of Work
+
+| Layer | Description | Artifact |
+| --- | --- | --- |
+| Pact | Cultural + process alignment for EntityAssistReactive | `PACT.md` |
+| Rules | Selected stacks + enforcement details | `RULES.md` (Stage 2) |
+| Guides | “How-to” instructions for CRTP builders, DB modules, CI | `GUIDES.md` (Stage 2) |
+| Implementation | Evidence that code follows the guides | `IMPLEMENTATION.md` (Stage 3) |
+
+## 4. Behavioral Agreements
+
+1. **Documentation-first:** No source changes until Stage 1 + Stage 2 docs are approved.
+2. **Topic-first Glossary:** Host glossary delegates to `rules/generative/backend/guicedee/GLOSSARY.md`, `rules/generative/backend/hibernate/GLOSSARY.md`, `rules/generative/backend/lombok/GLOSSARY.md`, `rules/generative/language/java/GLOSSARY.md`, and `rules/generative/platform/ci-cd/providers/github-actions.md` for canonical phrases.
+3. **Traceable diagrams:** Every C4/sequence/ERD diagram lives under `docs/architecture/` with Mermaid sources, linked from docs/PROMPT_REFERENCE.md.
+4. **Evidence capture:** Each stage notes unknowns (e.g., actual domain tables) instead of inventing artifacts.
+
+## 5. Technical Commitments
+
+- **Language:** Java 25 (JPMS) with Maven; reactive stack built on Mutiny and Hibernate Reactive.
+- **Integrations:** GuicedEE Core/Persistence modules, Vert.x 5 SQL client, Vert.x reactive database drivers (e.g., PostgreSQL), GitHub Actions workflow.
+- **Security:** Document trust boundaries between developer workstations, CI secrets, and database endpoints.
+- **Testing:** JUnit + GuicedEE testcontainers; coverage tooling deferred until Stage 2 rules specify Jacoco/Sonar.
+
+## 6. Collaboration Flow
+
+1. **Stage 1 (Architecture & Foundations):** Deliver PACT, docs/architecture diagrams, glossary, PROMPT_REFERENCE.
+2. **STOP for review.**
+3. **Stage 2 (Guides & Design Validation):** RULES + GUIDES referencing selected topics; update README and environment specs.
+4. **STOP for review.**
+5. **Stage 3 (Implementation Readiness):** IMPLEMENTATION.md, CI/env wiring confirmations, backlog of pending code changes.
+
+## 7. Closing Note
+
+This pact is referenced by all follow-up prompts. Any AI assistant working on EntityAssistReactive must load `PACT.md`, `docs/PROMPT_REFERENCE.md`, and the selected topic rules before proposing code or documentation updates.