azcodr 1.0.0

package/docs/rules/server_driven_ui.md

@@ -0,0 +1,71 @@
+# Server-Driven UI (SDUI) & Dynamic Theming
+
+> **Core Mandate:** Enforce metadata-driven UI rendering from declarative backend schemas, eliminating client-side tenant code forks, and inject white-label branding via W3C Design Tokens (DTCG).
+
+---
+
+## 1. Declarative Client-Agnostic SDUI Schema
+
+The backend provides a declarative UI layout schema describing fields, layouts, dynamic visibility rules (via Common Expression Language or JSON expressions), and allowed actions (`_actions`):
+
+```json
+{
+  "view": "OrderEdit",
+  "layout": "two-column",
+  "sections": [
+    {
+      "id": "general",
+      "title": "General Details",
+      "components": [
+        { "type": "TextInput", "id": "orderNumber", "label": "Order #", "readOnly": true },
+        { "type": "TextInput", "id": "custom_attributes.poNumber", "label": "PO Number", "required": true }
+      ]
+    },
+    {
+      "id": "tax",
+      "title": "Tax Exemption",
+      "visibleIf": "order.custom_attributes.isTaxExempt == true",
+      "components": [
+        { "type": "TextInput", "id": "custom_attributes.taxExemptionId", "label": "Tax ID", "required": true }
+      ]
+    }
+  ],
+  "_actions": [
+    { "action": "SUBMIT_FOR_APPROVAL", "label": "Submit Order", "method": "POST", "target": "/api/v1/orders/123/submit" }
+  ]
+}
+```
+
+---
+
+## 2. Multi-Platform Component Registries
+
+Frontend clients (Web, Mobile, Desktop) never contain hardcoded tenant branching. Each platform implements a local **Component Registry** mapping backend descriptors to native platform primitives:
+
+- **Web Clients**: Rendered dynamically via accessible primitives (Web Components, React, Vue, Svelte, or Solid).
+- **Mobile Clients**: Rendered natively via Flutter, iOS SwiftUI, or Android Jetpack Compose.
+- **Desktop Clients**: Rendered natively via Tauri or cross-platform toolkits.
+
+---
+
+## 3. Universal Design Tokens (W3C DTCG Standard)
+
+Manage tenant white-label branding and design systems via the **W3C Design Tokens Community Group (DTCG)** specification:
+
+```json
+{
+  "color": {
+    "brand": {
+      "primary": { "$value": "#1e40af", "$type": "color" },
+      "accent": { "$value": "#f59e0b", "$type": "color" }
+    }
+  },
+  "dimension": {
+    "radius": {
+      "base": { "$value": "6px", "$type": "dimension" }
+    }
+  }
+}
+```
+
+- **Universal Compilation**: Process tenant `tokens.json` files using **Style Dictionary** to compile dynamic themes at runtime for CSS Custom Properties (`--color-brand-primary`), Android XML / Compose, and iOS Swift tokens without code redeployments.

package/docs/rules/tenant_dynamic_schemas.md

@@ -0,0 +1,88 @@
+# Multi-Tenant Schema Extensibility & Virtual Entities
+
+> **Core Mandate:** Enforce dynamic schema extensibility via hybrid relational columns and validated JSON Schema (Draft 2020-12), prohibiting sparse nullable columns and branch-specific migrations in shared databases.
+
+---
+
+## 1. Hybrid Core + JSON/Document Extensibility
+
+Store universal relational attributes in standard typed columns. Store tenant-specific custom fields in a semi-structured `custom_attributes` column governed by tenant-scoped JSON Schemas:
+
+```sql
+CREATE TABLE customers (
+  id VARCHAR(64) PRIMARY KEY,
+  tenant_id VARCHAR(64) NOT NULL,
+  first_name VARCHAR(100) NOT NULL,
+  last_name VARCHAR(100) NOT NULL,
+  email VARCHAR(255) NOT NULL,
+  custom_attributes TEXT NOT NULL DEFAULT '{}',
+  created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE tenant_schema_definitions (
+  id VARCHAR(64) PRIMARY KEY,
+  tenant_id VARCHAR(64) NOT NULL,
+  entity_name VARCHAR(50) NOT NULL,
+  json_schema TEXT NOT NULL,
+  version INT NOT NULL DEFAULT 1,
+  UNIQUE(tenant_id, entity_name)
+);
+```
+
+### Runtime Validation Contract (JSON Schema Draft 2020-12)
+Validate all inbound custom attribute payloads at runtime against the tenant's compiled JSON Schema before persisting mutations:
+
+```
+┌────────────────────────────────────────────────────────┐
+│ Dynamic Schema Validator Contract (Agnostic)           │
+├────────────────────────────────────────────────────────┤
+│ validateCustomAttributes(schemaDef, data):             │
+│   compiledValidator = compileJsonSchema(schemaDef)     │
+│   result = compiledValidator.validate(data)           │
+│   if !result.isValid:                                  │
+│     return Failure(ValidationError(result.errors))     │
+│   return Success(data)                                 │
+└────────────────────────────────────────────────────────┘
+```
+Supported natively by open-source engines in every major language (`valico` in Rust, `gojsonschema` in Go, `jsonschema` in Python, `networknt` in Java, `ajv` in Node).
+
+---
+
+## 2. Meta-Schema Catalog for Virtual Custom Entities
+
+When tenants define completely custom entities/tables dynamically without deploying code:
+
+```sql
+CREATE TABLE tenant_entities (
+  id VARCHAR(64) PRIMARY KEY,
+  tenant_id VARCHAR(64) NOT NULL,
+  name VARCHAR(64) NOT NULL,
+  display_name VARCHAR(128) NOT NULL,
+  schema_definition TEXT NOT NULL,
+  UNIQUE(tenant_id, name)
+);
+
+CREATE TABLE tenant_records (
+  id VARCHAR(64) PRIMARY KEY,
+  tenant_id VARCHAR(64) NOT NULL,
+  entity_id VARCHAR(64) NOT NULL REFERENCES tenant_entities(id) ON DELETE CASCADE,
+  data TEXT NOT NULL DEFAULT '{}',
+  created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+```
+
+---
+
+## 3. Indexing Strategies for Dynamic Custom Attributes
+
+1. **Virtual / Generated Columns**: For high-throughput queried fields inside dynamic attributes, project them into virtual/generated columns and attach standard B-tree indexes:
+   ```sql
+   ALTER TABLE customers ADD COLUMN vat_number VARCHAR(64) 
+     GENERATED ALWAYS AS (custom_attributes->>'vat_number') STORED;
+   CREATE INDEX idx_customers_vat ON customers (tenant_id, vat_number);
+   ```
+2. **Functional / Expression Indexes**: Index specific nested attributes directly on engines that support expression indexes:
+   ```sql
+   CREATE INDEX idx_customers_po ON customers (tenant_id, ((custom_attributes->>'po_number')::text));
+   ```
+3. **Inverted Indexes**: Use generalized inverted indexing (e.g. GIN in PostgreSQL) for arbitrary key-value path searches.

package/docs/rules/tenant_pluggable_logic.md

@@ -0,0 +1,59 @@
+# Pluggable Multi-Tenant Business Logic & Workflows
+
+> **Core Mandate:** Eliminate `if-tenant` conditional branching via Strategy registries, Common Expression Language (CEL), durable workflow orchestration, and secure WebAssembly (Wasm) micro-sandboxes.
+
+---
+
+## 1. Strategy Pattern & Dynamic Strategy Registry
+
+Encapsulate diverging tenant algorithms into discrete strategies conforming to a unified domain port:
+
+```
+┌────────────────────────────────────────────────────────┐
+│ Discount Strategy Port Contract                        │
+├────────────────────────────────────────────────────────┤
+│ calculateDiscount(order): Decimal                      │
+└────────────────────────────────────────────────────────┘
+```
+
+The application maintains an in-memory Strategy Registry resolving the active strategy based on `tenant.subscriptionTier` or custom tenant config:
+
+```
+StrategyRegistry.register("standard", StandardDiscountStrategy)
+StrategyRegistry.register("enterprise_vip", HighVolumeTierStrategy)
+
+strategy = StrategyRegistry.resolve(tenant.discountStrategyKey)
+discount = strategy.calculateDiscount(order)
+```
+
+---
+
+## 2. Declarative Rule Evaluation: Common Expression Language (CEL)
+
+Allow tenants or administrators to configure dynamic conditional logic stored as declarative text or JSON without redeploying binaries. Standardize on **Common Expression Language (CEL)**:
+
+```cel
+// Example Tenant Rule Expression:
+order.total >= 500 && order.shipping_country == "US" && tenant.tier == "ENTERPRISE"
+```
+
+- **Memory-Safe & Non-Turing Complete**: Prevents infinite loops, recursion crashes, and side-effects.
+- **Polyglot Portability**: Native compilers and runtimes available across Go (`cel-go`), Rust (`cel-rust`), Python (`cel-python`), Java (`cel-java`), and TypeScript (`cel-js`).
+
+---
+
+## 3. Durable Workflows & Orchestration (Temporal / BPMN 2.0)
+
+For tenants with diverging multi-step approval, fulfillment, or refund lifecycles:
+- **Durable Execution Engines**: Standardize on **Temporal.io** or **Camunda 8 / Zeebe (BPMN 2.0)**.
+- **Resilience Guarantees**: Workflows automatically persist state across node crashes, manage timeouts, execute automatic retries, and trigger compensation transactions (Saga pattern) across polyglot workers.
+- **Tenant Workflow Selection**: The domain routes entity state transitions to tenant-specific workflow IDs configured in database metadata.
+
+---
+
+## 4. Secure Script Sandboxing: WebAssembly (Wasm / Extism)
+
+Never execute untrusted tenant strings via host runtime evaluation (`eval()`, dynamic reflection, or unshielded isolates).
+- **Universal Sandboxing with Extism / Wasmtime**: Tenants compile custom logic (in Rust, Go, Python, or TypeScript) to portable `.wasm` bytecode.
+- **Strict Execution Quotas**: Max 50ms CPU execution budget, max 16MB linear memory boundary.
+- **Complete Host Isolation**: Sandboxed instances possess zero access to host filesystem, network sockets, environment variables, or database connections unless explicitly passed via memory interfaces.

package/docs/rules/test_driven_development.md

@@ -0,0 +1,106 @@
+# Test-Driven Development (London School TDD) & Agile Domain Lifecycle
+
+> **Core Mandate:** Drive all features through the non-negotiable 5-Phase Agile Domain Lifecycle: Requirements ➔ Domain Analysis ➔ Outer Acceptance Test (RED) ➔ Inner Unit Test (RED-GREEN-REFACTOR) ➔ Outer Verification (GREEN). Never deviate from this sequence.
+
+---
+
+## 1. The Immutable 5-Phase Agile Domain Lifecycle
+
+Every functional increment, feature, or architectural modification must traverse this unbroken sequence. Writing code out of order (e.g. coding before tests, or testing before domain analysis) is strictly prohibited.
+
+```
+┌────────────────────────────────────────────────────────────────────────────────────────┐
+│                        THE NON-NEGOTIABLE AGILE DOMAIN LIFECYCLE                       │
+└────────────────────────────────────────────────────────────────────────────────────────┘
+
+  [Phase 1: Requirements Engineering]
+     │  - Decompose user prompt into INVEST user stories.
+     │  - Author executable Gherkin Given-When-Then criteria.
+     │  - Define Out-of-Scope non-goals and edge case status code matrix.
+     ▼
+  [Phase 2: Tactical Domain Analysis]
+     │  - Discover and enforce Ubiquitous Language terms.
+     │  - Map Bounded Contexts, Aggregate Roots, and Value Objects.
+     │  - Codify explicit business invariants that state mutations must protect.
+     ▼
+  [Phase 3: Outer-Loop Acceptance Test (RED)]
+     │  - Write failing end-to-end acceptance or contract test:
+     │      * Frontend: Component/UI user interaction assertion (Playwright / testing library).
+     │      * Backend: Black-box HTTP API contract test (Supertest/OpenAPI).
+     │  - Verify the test FAILS for the expected reason (RED proof).
+     ▼
+  [Phase 4: Inner-Loop TDD & Collaborator Discovery (RED-GREEN-REFACTOR)]
+     │  - Outer test discovers required collaborators (Use Cases, Ports, Domain Entities).
+     │  - For each collaborator:
+     │      1. RED: Write failing unit test asserting domain invariants.
+     │      2. GREEN: Write minimal production code to pass.
+     │      3. REFACTOR: Eliminate duplication, enforce SLAP, CQS, Clean Code.
+     ▼
+  [Phase 5: Outer Acceptance Resolution & Definition of Done]
+        - Run outer acceptance test: verifies GREEN without altering the test assertion.
+        - Run cross-package boundary smoke tests (reverse proxy, sockets, LAN interfaces).
+        - Verify 100.00% test coverage gate across all packages.
+        - Pass Definition of Done (DoD) checklist.
+```
+
+---
+
+## 2. Outside-In TDD (London School) Double Loop
+
+Drive all user-facing features from the outermost interface inward:
+
+```
+[Outer Loop: Acceptance / Contract Test (RED)]
+       │
+       ▼
+[Inner Loop: Unit Test Collaborator (RED)] ──► [Implement Minimal Code (GREEN)] ──► [Refactor (REFACTOR)]
+       │                                                                                   │
+       └──────────────────────── Repeat Inner Loop until Done ◄────────────────────────────┘
+       │
+       ▼
+[Outer Loop: Acceptance / Contract Test (GREEN)] ──► [Outer Refactor]
+```
+
+1. **Outer Acceptance / Contract Test First**: Every feature begins with a failing outer acceptance test:
+   - **Frontend (UI)**: Component or page tests asserting user interactions, form submissions, accessibility, and visual states.
+   - **Backend (API)**: Black-box REST route tests asserting HTTP verbs, request schemas, RFC 7807 problem details, and status codes.
+2. **Collaborator Discovery**: Outer tests do not implement business logic directly; they discover and shape the contracts of their immediate collaborators (Use Cases, Domain Services, Repositories).
+3. **Inner Unit Tests with Test Doubles**: Unit test collaborators in isolation using test doubles and mocks (`Controllers/Handlers` ➔ `Use Cases` ➔ `Ports/Adapters`).
+4. **Mock Ownership Principle**: **Only mock types you own**. Always wrap third-party libraries, database drivers, and external network clients in application-owned port adapters before mocking.
+5. **Atomic Double Loop**: Follow the strict rhythm: **RED (Fail) ➔ GREEN (Pass) ➔ REFACTOR (Clean/De-duplicate)**. Never skip the Refactor phase.
+6. **Cross-Package Boundary Verification**: In monorepos with frontend dev servers or API gateways (Vite, NGINX), outer-loop verification must explicitly test reverse-proxy forwarding and real network serialization (`scripts/smoke_test.sh`), ensuring client-side SPA fallbacks do not mask unmapped backend routes.
+
+---
+
+## 3. The Zero-Deviation Invariant (Why We NEVER Deviate)
+
+Deviating from this lifecycle introduces catastrophic defects and architectural rot:
+
+| Deviation Shortcut | Immediate Consequence | Systemic Impact |
+|---|---|---|
+| **Skipping Domain Analysis** | Hallucinated entities, missing business invariants, wrong data models. | "The Toy Prototype Blunder": Foreign key string inputs, unvalidated states, costly migrations. |
+| **Writing Code Before Tests** | Untested edge cases, unfalsifiable code, confirmation bias in test design. | Hidden bugs in production, regressions during refactoring, brittle codebases. |
+| **Skipping Outer Acceptance Tests** | In-memory unit tests pass, but user interactions and network routing fail. | "The In-Memory Supertest Illusion": App says "Offline/Connecting" while 100% unit tests pass. |
+| **Skipping the Refactor Phase** | Technical debt accumulates immediately behind green tests. | Code rot, duplicated logic, bloated monolithic functions (> 30 lines), violated DRY/SLAP. |
+
+### The Immutable Laws of TDD Execution:
+1. **No Production Code Without a Failing Test:** You are not allowed to write any production code unless it is to make a failing unit or acceptance test pass.
+2. **No Test Without Prior Domain Understanding:** You are not allowed to write a test without knowing the Ubiquitous Language, Aggregate Root, and business invariants it asserts.
+3. **Minimal Code Only:** Write only the minimal amount of code necessary to turn the failing test green. Do not anticipate speculative future requirements.
+4. **Refactor Under Green Only:** Never alter production code structure while tests are red. Refactor only when all existing assertions are green.
+
+### DO's:
+- **DO:** Strictly adhere to the 5-Phase Agile Domain Lifecycle: Requirements ➔ Domain Analysis ➔ Outer Acceptance Test (RED) ➔ Inner Unit Test (RED-GREEN-REFACTOR) ➔ Outer Verification (GREEN).
+- **DO:** Follow Outside-In TDD (London School): Outer acceptance test ➔ collaborator discovery ➔ unit tests with test doubles.
+- **DO:** Maintain 100.00% line, branch, statement, and function coverage across all backend, contract, and frontend suites.
+- **DO:** Verify cross-package integration boundaries (Vite dev server reverse proxy, real network sockets, HTTP client JSON parsing) with automated full-stack smoke tests (`scripts/smoke_test.sh`).
+- **DO:** Keep functions small (under 20–30 lines) adhering to Single Level of Abstraction (SLAP) and Command-Query Separation (CQS).
+
+### DONT's:
+- **DONT:** Never write a single line of production code without an existing failing test driving it.
+- **DONT:** Never write a test without prior domain analysis (Ubiquitous Language and invariant definition). Tests must assert domain invariants, not arbitrary syntax.
+- **DONT:** Never mock types you do not own; always wrap third-party dependencies in application-owned adapters.
+- **DONT:** Never equate in-memory test double passes (e.g. Supertest against in-memory Express instances) with real network transport, reverse proxying, or end-to-end user connectivity.
+- **DONT:** Never skip the Refactor phase under green; technical debt must not accumulate behind green tests.
+- **DONT:** Never use arbitrary `setTimeout()` or `sleep()` in tests; use deterministic event polling (`waitFor`).
+

package/docs/rules/test_isolation.md

@@ -0,0 +1,26 @@
+# Test Coverage, Isolation & Determinism
+
+> **Core Mandate:** Enforce 100.00% test coverage thresholds, transactional database rollback per test, deterministic data factories, and zero-sleep flakiness elimination across all test suites.
+
+---
+
+## 1. Mandatory 100.00% Test Coverage Thresholds
+
+- **Strict Coverage Thresholds**: Maintain line, function, branch, and statement test coverage at **100.00%** across all backend domain logic, adapters, contracts, and frontend suites. Strictly enforce 100% threshold failure gates in CI pipelines.
+- **Exhaustive Status Codes & Error Branches**: Explicitly test all HTTP/gRPC response codes:
+  - Success: `200 OK`, `201 Created`, `204 No Content`
+  - Client Errors: `400 Bad Request`, `401 Unauthorized`, `403 Forbidden`, `404 Not Found`, `409 Conflict`, `422 Unprocessable Entity`, `429 Too Many Requests`
+  - Server Failures: `500 Internal Server Error`, `503 Service Unavailable`
+- **UI Interaction States & Edge Cases**: Fully assert all presentation states (loading spinners, disabled controls, error banners, success feedback, empty states) across suites.
+
+---
+
+## 2. Database Test Isolation & Zero Flakiness
+
+- **Transactional Rollback per Integration Test**:
+  - Every integration test that interacts with persistence must execute within a scoped transaction that is rolled back upon test completion (`afterEach` rollback) or use ephemeral, disposable database isolates. Never leave mutated rows that pollute subsequent tests.
+- **Deterministic Test Data Factories**:
+  - Utilize strongly-typed test data factories (`buildUser()`, `buildOrder()`) with randomized unique identifiers rather than hardcoded magic strings or fixed database IDs.
+- **Zero Sleep / Flakiness Elimination**:
+  - Strictly forbid arbitrary `sleep()` or timeout pauses in tests.
+  - Rely exclusively on deterministic condition polling (`waitFor(condition)`) or reactive event promises to eliminate test flakiness.

package/docs/rules/transactional_email.md

@@ -0,0 +1,20 @@
+# Transactional Email Subsystem
+
+> **Core Mandate:** Enforce declarative email templates, safe variable interpolation, and deterministic local test delivery through Mailpit SMTP routing.
+
+---
+
+## 1. Declarative & Typed Email Templates
+
+- **Declarative Template Definition**: Author transactional email templates using language-agnostic markup formats (such as **MJML - Mailjet Markup Language**) or typed component schemas to ensure cross-client rendering consistency across Outlook, Gmail, and Apple Mail.
+- **Safe Variable Interpolation**: Strictly prohibit unescaped raw HTML string concatenation. Always use context-aware template engines that automatically escape HTML special characters to prevent Cross-Site Scripting (XSS) and injection vulnerabilities.
+
+---
+
+## 2. Local Mail Transport & Integration Verification
+
+- **Local SMTP via Mailpit**:
+  - Route local and CI SMTP traffic to **Mailpit** (SMTP port 1025 / Web UI port 8025).
+  - Never route emails to public mail transfer agents (MTAs) or external API gateways during automated test runs or local development.
+- **Deterministic API Assertion Protocol**:
+  - Assert email delivery in integration tests by querying Mailpit's REST API (`GET /api/v1/messages`) to inspect recipient headers, delivery status, HTML body content, and verification links without timing dependencies.

package/docs/rules/typescript.md

@@ -0,0 +1,55 @@
+# Static Type Safety & Sound Type Systems
+
+> **Core Mandate:** Enforce maximum compiler strictness, branded nominal typing for domain identifiers, strict prohibition of untyped escape hatches, and automated pre-commit quality guardrails across polyglot implementations.
+
+---
+
+## 1. Maximum Compiler Strictness & Soundness
+
+Regardless of the execution language chosen for an adapter or service, enforce maximum compiler rigor to eliminate runtime null pointer exceptions, unhandled type cases, and memory errors at compile time:
+
+- **TypeScript**: Enable all strict compiler flags (`strict: true`, `noImplicitAny: true`, `strictNullChecks: true`, `noUncheckedIndexedAccess: true`).
+- **Rust**: Enable `#![deny(clippy::all)]` and `#![deny(missing_docs)]` with zero `unsafe` blocks.
+- **Go**: Enable comprehensive static analysis (`golangci-lint` with `errcheck`, `govet`, `staticcheck`).
+- **Python**: Enforce strict type checking (`mypy --strict` or `pyright`).
+
+---
+
+## 2. Branded Nominal Typing & Primitive Obsession Elimination
+
+Prevent accidental mixing of raw primitive identifiers (e.g. passing an arbitrary `string` representing a `TenantId` where a `UserId` is expected) by enforcing nominal types:
+
+```
+┌────────────────────────────────────────────────────────┐
+│ Nominal Domain Identifier Pattern (Polyglot)           │
+├────────────────────────────────────────────────────────┤
+│ Rust:       struct TenantId(String);                   │
+│             struct UserId(String);                     │
+│ Go:         type TenantId string                       │
+│             type UserId string                         │
+│ TypeScript: type TenantId = Brand<string, 'TenantId'>; │
+│             type UserId = Brand<string, 'UserId'>;     │
+│ Python:     TenantId = NewType('TenantId', str)        │
+│             UserId = NewType('UserId', str)            │
+└────────────────────────────────────────────────────────┘
+```
+
+Domain functions must accept and return branded types rather than raw primitive strings or integers.
+
+---
+
+## 3. Strict Prohibition of Untyped Escape Hatches
+
+- **Zero Tolerance for Unsound Types**: Strictly prohibit `any` in TypeScript, raw `interface{}` / `any` without type assertion checks in Go, raw `Any` in Python, or unchecked casts in Java/Rust.
+- **Runtime Validation at Boundaries**: External payloads (network requests, message queues, disk files) must be parsed and narrowed into strongly-typed domain structures before passing to application services.
+- **Commit Guardrails**: Enforce Conventional Commits via commit linters. Never bypass pre-commit hooks running static type checking, formatting, and linters.
+
+---
+
+## 4. Module Path Aliases & Relative Traversal Elimination
+
+- **Path Alias Mandate (`@/*`)**: All TypeScript packages in the workspace must configure and standardize on `@/*` mapped to `./src/*` across `tsconfig.json` (`"baseUrl": "."`, `"paths": { "@/*": ["./src/*"] }`), bundlers (Vite `resolve.alias`), and test runners (Vitest `resolve.alias`).
+- **Strict Prohibition of Deep Relative Traversal**: Never use deep relative traversals (`../../../..`, `../../..`, `../..`) across layers or contexts. Deep relative paths create fragile coupling, impair refactoring, and obscure domain layer boundaries.
+- **Node.js ESM Production Resolution**: In backend environments executing compiled JavaScript under Node.js ESM (`node dist/index.js`), use `tsc-alias` post-compilation (`tsc && tsc-alias`) to resolve path aliases in `dist/` to valid relative paths without introducing runtime loader overhead.
+- **Scope of Sibling Imports**: Local relative imports (`./file.js`) are permitted only for immediate siblings within the identical directory. Any import traversing up a directory hierarchy or crossing architectural boundaries (domain, ports, adapters, components, context) MUST resolve via `@/*`.
+

package/docs/rules/ui_navigation.md

@@ -0,0 +1,20 @@
+# UI Navigation & URL State Synchronization
+
+> **Core Mandate:** Enforce bidirectional URL state synchronization for all interactive view states, preserving deep linkability, bookmarkability, and native browser navigation.
+
+---
+
+## 1. Bidirectional URL State Synchronization
+
+Every view state that represents navigation, active tab, filtering, sorting, pagination, or search query must synchronize bidirectionally with URL search parameters (`useSearchParams`):
+- **Bookmarkability**: A user copying the browser URL must be able to restore the exact view, active tab, filter selections, and pagination page on any device.
+- **Browser History Integration**: The browser's back and forward buttons must navigate between state transitions smoothly without triggering full page reloads.
+
+---
+
+## 2. Deep Linking Standards
+
+- **Tabbed Interfaces**: Encode active tab keys in query params (e.g. `?tab=security` or `/settings/security`).
+- **Data Tables & Lists**: Preserve table states in URL parameters:
+  - `?page=2&limit=25&sort=createdAt&order=desc&status=ACTIVE`
+- **Modal & Drawer States**: If a modal or drawer represents an actionable sub-view (e.g. `?modal=edit-user&userId=123`), synchronize it with the URL so direct links open the intended context.

package/docs/rules/ui_ux_architecture.md

@@ -0,0 +1,168 @@
+# UI/UX Architecture, Design Triage & Role-Based Navigation System
+
+> **Core Mandate:** Enforce mandatory upfront Design Architecture Triage before writing UI code, a strict dual-experience model separating Enterprise Operator Workspaces from Consumer / Member Self-Service Portals, a persistent application shell with collapsible sidebar navigation, bidirectional URL state synchronization, and strict decoupling of developer demo personas from production authentication.
+
+---
+
+## 1. The Design Architecture Triage Gate
+
+A catastrophic software defect occurs when design architecture is not triaged upfront—resulting in ad-hoc navigation, mixed-up user roles, toy-like prototypes, and broken user journeys.
+
+Before a single UI component or view is built, every interface increment must pass the **7-Pillar Design Architecture Triage Gate**:
+
+```
+1. ROLE & IDENTITY TRIAGE      ──► Who is the user? What is their exact operational domain and boundary?
+2. INFORMATION ARCHITECTURE    ──► What is the hierarchy? Persistent Shell vs. Dynamic Canvas?
+3. EXPERIENCE DUALITY          ──► Operator Enterprise Workspace (dense) vs. Member Consumer Portal (simple)?
+4. NAVIGATION & WAYFINDING     ──► Collapsible sidebar, breadcrumbs, command palette (Cmd+K), mobile drawer?
+5. STATE & URL SYNCHRONIZATION ──► Deep-linkable search params (?tab=, ?q=, ?page=, ?modal=)?
+6. ACCESS & ROUTE PROTECTION   ──► Strict route guards (<ProtectedRoute>), role redirection, 403 handling?
+7. ACCESSIBILITY & FEEDBACK    ──► WCAG 2.2 AA, focus trapping, ARIA live regions, zero browser-native alerts?
+```
+
+---
+
+## 2. App Shell Architecture: Persistent Shell vs. Dynamic Canvas
+
+The application interface is strictly divided into two distinct anatomical zones:
+
+```
++----------------------------------------------------------------------------------------------------+
+| PERSISTENT GLOBAL HEADER                                                                           |
+| [Brand / Logo] | [Organization Context Switcher] | [Command Palette Cmd+K] | [Alerts] | [User Menu]|
++------------------------------------+---------------------------------------------------------------+
+| PERSISTENT OPERATOR SIDEBAR        | DYNAMIC VIEWPORT CANVAS                                       |
+| (Collapsible to 64px Icon Rail)    |                                                               |
+|                                    | 1. CONTEXTUAL BREADCRUMBS                                     |
+| - Overview (Dashboard)             |    Home > Resources > Resource Alpha > Details                |
+| - Operations (Catalogs, Resources) | ------------------------------------------------------------- |
+| - Transactions (Orders, Invoices)  | 2. PAGE HEADER & PRIMARY ACTION CTA                           |
+| - Financials (Ledger, Settlements) |    [Page Title]               [Filter] [+ Primary Action CTA] |
+| - Services (Requests, Tickets)     | ------------------------------------------------------------- |
+| - Settings (Team, Roles, Org)      | 3. URL-SYNCHRONIZED TABS & SEARCH BAR                         |
+| ---------------------------------- |    [Active (12)] [Draft (2)] [Archived (0)]  [Search...]      |
+| [System Health Badge]              | ------------------------------------------------------------- |
+| [Collapse / Expand Toggle Button]  | 4. DATA PRESENTATION CANVAS                                   |
+|                                    |    (Data Tables, Metric Grids, Detail Drawers, Dialogs)       |
++------------------------------------+---------------------------------------------------------------+
+| PERSISTENT STATUS / FOOTER (System Context, Active Role Indicator, Accessible Live Regions)         |
++----------------------------------------------------------------------------------------------------+
+```
+
+### 2.1. The Persistent Shell (Never Re-rendered Across Page Navigations)
+- **Top Header**:
+  - **Brand Anchor**: Visual identity and immediate home navigation.
+  - **Organization Context Switcher**: Dropdown selector allowing operators to switch multi-tenant organization contexts (`organizationId`) with automatic data re-fetching.
+  - **Command Palette (`Cmd + K` / `Ctrl + K`)**: Global keyboard-first navigation and entity search.
+  - **Notification Center**: Bell icon with unread count badge displaying critical alerts (approvals, overdue items, system events).
+  - **User Profile & Account Menu**: User avatar, full name, role badge, account settings, and secure sign-out.
+- **Collapsible Sidebar (Desktop Operator View)**:
+  - Default expanded (`w-64` / 256px) with categorized section headings and labels.
+  - Collapses smoothly into a slim icon-only rail (`w-16` / 64px) with hover tooltips and active indicator pills.
+  - Collapse state is persisted in `localStorage` (`app_sidebar_collapsed`).
+  - Mobile view collapses into a slide-over off-canvas sheet triggered by a hamburger button.
+- **Accessible Feedback Layer**:
+  - Floating toast container and ARIA live regions for mutation confirmations (`role="status"`) and errors (`role="alert"`).
+
+### 2.2. The Dynamic Canvas (Contextual to Active Route & User Role)
+- **Primary Action Buttons (CTAs)**: Operator sees "+ Create Resource" or "Approve Transaction"; Member sees "Submit Request" or "Make Payment".
+- **Data Table Columns**: Operators see customer contact info, financial amounts, and audit fields (`createdBy`); Members see only their own personal records.
+- **Metric Widgets & Dashboards**: Operators see organization cash flow, throughput, and review queues; Members see personal account status and open request progress.
+
+---
+
+## 3. Dual-Experience Model: Operator Workspace vs. Consumer / Member Portal
+
+To prevent confusing operators with consumer simplicity and overwhelming consumers with enterprise complexity, applications enforce **Two Completely Distinct Experiences**:
+
+| Architectural Dimension | Enterprise Operator Workspace | Consumer / Member Portal (`/portal`) | Public Catalog / Landing (`/catalog`) |
+|---|---|---|---|
+| **Target Roles** | `ADMIN`, `OPERATOR`, `MANAGER`, `AUDITOR` | `MEMBER`, `CONSUMER`, `CUSTOMER` | Unauthenticated Visitors, Prospective Users |
+| **Route Prefix** | `/` (e.g. `/resources`, `/orders`, `/analytics`) | `/portal` (e.g. `/portal`, `/portal/orders`, `/portal/support`) | `/catalog`, `/onboarding` |
+| **Navigation Pattern** | Collapsible left sidebar with categorized sections | Clean top navigation bar + mobile bottom navigation bar | Simple landing header with "Sign In" CTA |
+| **Information Density** | High density, tabular grids, advanced multi-filters | Low-to-medium density, card-centric, touch ergonomics | Visual cards, featured items, search badges |
+| **Data Scope** | Organization-wide (all entities, transactions, ledgers) | Member-scoped (strictly own entities, orders, requests) | Public records with status `AVAILABLE` / `ACTIVE` |
+| **Primary Goal** | Operational throughput, oversight, compliance, auditing | Self-service autonomy, rapid actions, account visibility | Resource discovery and user onboarding |
+
+---
+
+## 4. Production Authentication UX vs. Developer Persona Harness
+
+### 4.1. Strict Decoupling Mandate
+- **NEVER** embed test personas ("Admin Alice", "Operator Bob", "Member Charlie") into production sign-in forms or modals. Conflating demo personas with actual authentication makes the application feel like a toy prototype and creates severe security/UX confusion.
+- **Production Sign-In (`/login`)**:
+  - Clean, dedicated sign-in page or clean modal.
+  - Email address and password inputs with real-time Zod schema validation.
+  - Accessible error alerts (`role="alert"`).
+  - Clear "Remember me" option and "Forgot password?" recovery link.
+  - Dedicated registration tab or `/register` route for onboarding new tenant organizations.
+- **Developer / Demo Persona Test Harness**:
+  - Must be **100% decoupled** from the production sign-in form.
+  - Rendered strictly via a dedicated **Dev Floating Toolbar** or bottom-right drawer:
+    ```tsx
+    // Only rendered in development / preview mode
+    if (import.meta.env.DEV) {
+      return <DevPersonaToolbar />;
+    }
+    ```
+  - Visibly labeled: `[DEV ENVIRONMENT: Switch Persona]`.
+  - Switching personas clears active query caches, updates auth context, and triggers role-appropriate post-login redirection.
+
+---
+
+## 5. Role-Based Access Control & Route Guarding
+
+- **Defense in Depth**:
+  - Hiding a button via `<Can permission="...">` is an ergonomic convenience, **never security**.
+  - All routes must be protected by declarative route guards:
+    ```tsx
+    <Route element={<ProtectedRoute requiredRoles={['ADMIN', 'OPERATOR']} />}>
+      <Route path="/resources" element={<ResourcesPage />} />
+      <Route path="/transactions" element={<TransactionsPage />} />
+    </Route>
+    ```
+- **Automatic Post-Login Role Routing**:
+  - When a user logs in:
+    - Roles `ADMIN`, `OPERATOR`, `MANAGER` ➔ Redirect to `/` (Operator Executive Dashboard).
+    - Role `MEMBER`, `CONSUMER` ➔ Redirect to `/portal` (Self-Service Portal Home).
+    - Unauthenticated users attempting to access protected routes ➔ Redirect to `/login?returnTo=...`.
+    - Authenticated users accessing routes without permission ➔ Display an accessible 403 Forbidden screen with a "Return to Home" button.
+
+---
+
+## 6. Bidirectional URL State Synchronization
+
+Per [`docs/rules/ui_navigation.md`](./ui_navigation.md), all view state that represents navigation, active tab, filtering, sorting, pagination, or search query must synchronize bidirectionally with URL search parameters (`useSearchParams`):
+1. **Tabs**: `?tab=active`, `?tab=draft`, `?tab=archived`
+2. **Filters**: `?status=ACTIVE&category=cloud`
+3. **Search Queries**: `?q=alpha`
+4. **Pagination**: `?page=2&pageSize=25`
+5. **Drawers / Modals**: `?drawer=resource-102` or `?modal=create-order`
+
+---
+
+## 7. Invariants, DO's & DONT's
+
+### DO:
+- **DO** execute the 7-Pillar Design Architecture Triage before writing any UI code.
+- **DO** provide a collapsible left sidebar for operators that transitions into a slim 64px icon rail with hover tooltips and persists state in `localStorage`.
+- **DO** provide a dedicated, consumer-focused `/portal` layout for Members/Consumers with top and mobile-bottom navigation.
+- **DO** provide a public `/catalog` view for unauthenticated visitors to discover resources.
+- **DO** isolate developer demo personas into a dedicated dev-only floating toolbar (`import.meta.env.DEV`), completely decoupled from the real sign-in form.
+- **DO** enforce route guards on all routes, automatically redirecting users according to their authenticated role.
+- **DO** synchronize tabs, search terms, and pagination with URL search parameters.
+- **DO** use accessible Radix UI dialogs (`<ConfirmDialog>`) for destructive actions and ARIA live regions for status alerts.
+- **DO** synchronize authentication and tenant selection across browser tabs via `window.addEventListener('storage')`, and isolate complex subcomponents or page outlets using accessible `<ErrorBoundary>` components to prevent unhandled render exceptions from crashing the application shell.
+- **DO** decouple all technical internal telemetry (API gateway connection states, hexagonal port health, database adapter indicators, and active security roles) from user-facing screens and confine them exclusively to development tools and harnesses gated by `import.meta.env.DEV`.
+- **DO** centralize all user interface copy, status labels, error notifications, action titles, and templated messages into configuration constants (`UI_STRINGS`) to eliminate scattered hardcoded strings.
+
+### DONT:
+- **DONT** build UI views on assumptions without completing the Design Architecture Triage Gate.
+- **DONT** embed mock/demo personas inside user-facing login or registration forms.
+- **DONT** force Member/Consumer users to navigate the enterprise operator sidebar with disabled buttons.
+- **DONT** expose multi-tenant organization switchers or system audit fields to consumer roles.
+- **DONT** expose internal architecture jargon (e.g. "ACID ledger", "Hexagonal ports", "API Connected", "Active Role") in production user-facing or administrator views.
+- **DONT** hardcode error messages, status labels, or button copy directly in page components; reference centralized configuration constants.
+- **DONT** use browser-native `window.alert()` or `window.confirm()` popups.
+- **DONT** rely solely on hiding UI buttons to enforce authorization; always wrap routes in `<ProtectedRoute>`.
+- **DONT** lose search queries or active tab states upon page reload; always sync to URL search params.