feat(dx): Phase 1 — universal dev environment setup

.claude/rules/cicd-workflows.md

@@ -0,0 +1,28 @@
+---
+paths:
+  - ".github/workflows/*.yml"
+  - ".github/actions/**/*"
+---
+
+# CI/CD Workflow Patterns
+
+## Structure
+
+Workflows follow a naming convention with two tiers:
+
+- **Orchestrators** (`cicd_1-pr.yml` through `cicd_8-*.yml`) -- top-level workflows triggered by events (PR, merge queue, nightly, release). Each calls reusable component workflows.
+- **Components** (`cicd_comp_*.yml`) -- reusable workflows (`workflow_call`) for individual phases: build, test, deploy, finalize. Called by orchestrators, never triggered directly.
+- **Other** (`ai_*.yml`) -- non-CI workflows (e.g., AI agent orchestration).
+
+## Security constraint (CRITICAL)
+
+PR check workflows (`cicd_1-pr.yml`) run on **unmerged code** and must NOT use secrets. Any notification or action requiring secrets belongs in a separate post-workflow (triggered after the PR workflow completes, runs on the base branch).
+
+## When modifying workflows
+
+- Check if the change belongs in an orchestrator or a component. Component changes affect all orchestrators that call them.
+- Test with `act` or by pushing to a branch and checking the Actions tab.
+- The cicd-diagnostics skill can help debug workflow failures.
+
+## On-demand
+- See `docs/infrastructure/` for CI/CD architecture details.

.claude/rules/doc-updates.md

@@ -0,0 +1,30 @@
+---
+paths:
+  - "**/*.mdc"
+  - "CLAUDE.md"
+  - "AGENTS.md"
+  - ".claude/rules/*"
+  - ".cursor/rules/*"
+  - ".github/copilot-instructions.md"
+  - "docs/**/*"
+---
+
+# Documentation Updates
+
+## Single source of truth
+- **AGENTS.md** -- navigation and quick reference only.
+- **`/docs/`** -- full patterns by domain (backend, frontend, testing, etc.).
+- **`.claude/rules/`** -- short reminders scoped by file path; reference `/docs/`, don't duplicate.
+- **`.claude/skills/`** -- workflows and procedures; reference supporting files for detail.
+
+## Where to update
+- **Java/Config/REST/DB** -> `docs/backend/*.md`
+- **Angular/tests/styles** -> `docs/frontend/*.md`
+- **Build/CI/Docker** -> `docs/core/`, `docs/backend/MAVEN_BUILD_SYSTEM.md`, `docs/infrastructure/`
+- **Testing** -> `docs/frontend/TESTING_FRONTEND.md`, `docs/testing/*.md`
+
+## Context architecture
+- See `docs/claude/CONTEXT_ARCHITECTURE.md` for decision framework on where to place new instructions.
+
+## Quality
+- Use examples. Cross-reference instead of duplicating. Document aliases, not raw commands.

.claude/rules/e2e-rules.md

@@ -0,0 +1,38 @@
+---
+paths:
+  - "core-web/apps/dotcms-ui-e2e/**/*.spec.ts"
+  - "e2e/**/*.spec.ts"
+---
+
+# E2E Test Conventions (Playwright)
+
+## Page Object Model (POM)
+- **One class per page** -- each page has its own Page Object
+- **Encapsulate interactions** -- all `page.fill()`, `page.click()` go in Page Objects, not tests
+- **Tests use Page Objects only** -- never interact with DOM directly in test files
+
+## Selectors: ALWAYS use data-testid
+
+```typescript
+// CORRECT
+await this.page.getByTestId("userNameInput").fill(username);
+await this.page.getByTestId("submitButton").click();
+
+// WRONG -- never use CSS selectors
+await this.page.locator('input[id="userId"]').fill(username);
+```
+
+## File naming
+- Page Objects: `[PageName].page.ts`
+- Components: `[ComponentName].component.ts`
+- Tests: `[FeatureName].spec.ts`
+- Test data: `[FeatureName]Data.ts`
+
+## Commands
+```bash
+just test-e2e-node                              # full suite
+just test-e2e-node-specific test=login.spec.ts  # single spec
+just test-e2e-node-debug-ui test=login.spec.ts  # Playwright UI mode
+```
+
+See `e2e/dotcms-e2e-node/README.md` for full documentation.

.claude/rules/frontend-context.md

@@ -0,0 +1,30 @@
+---
+paths:
+  - "core-web/**/*.ts"
+  - "core-web/**/*.tsx"
+  - "core-web/**/*.html"
+  - "core-web/**/*.scss"
+  - "core-web/**/*.css"
+---
+
+# Frontend Context (core-web)
+
+**Nx monorepo** in `core-web/`: TypeScript, Angular apps/libs, and SDK for **Angular** and **React**. Full standards live in **`docs/frontend/`**. See `core-web/AGENTS.md` for commands, conventions, and structure.
+
+## Stack
+- **Angular**: standalone, signals, `inject()`, `input()`/`output()`, `@if`/`@for`, OnPush, PrimeNG/PrimeFlex. Check `core-web/package.json` for current version.
+- **SDK**: `sdk-angular`, `sdk-react`, `sdk-client`, `sdk-types`, etc.
+
+## Quick reminders (details in docs)
+- **Angular**: `$` prefix for signals, `$` suffix for observables; no `standalone: true`; OnPush; `[class.x]` / `[style.x]` (no ngClass/ngStyle); host bindings in `host: {}`.
+- **Testing**: Spectator + Jest; `data-testid` on elements; `byTestId()`, `spectator.setInput()`, `mockProvider()`; never set component inputs directly. Use `@dotcms/utils-testing` createFake functions.
+- **TypeScript**: Strict types, no `any` (use `unknown`), `as const` instead of enums, `#` for private.
+- **Services**: Single responsibility; `providedIn: 'root'`; use `inject()` instead of constructor injection.
+
+## On-demand
+- `docs/frontend/ANGULAR_STANDARDS.md`
+- `docs/frontend/COMPONENT_ARCHITECTURE.md`
+- `docs/frontend/TESTING_FRONTEND.md`
+- `docs/frontend/STATE_MANAGEMENT.md`
+- `docs/frontend/TYPESCRIPT_STANDARDS.md`
+- `docs/frontend/STYLING_STANDARDS.md`

.claude/rules/java-context.md

@@ -0,0 +1,39 @@
+---
+paths:
+  - "**/*.java"
+  - "dotCMS/src/**/*"
+---
+
+# Java Backend Context
+
+## Imports
+```java
+import com.dotmarketing.util.Config;
+import com.dotmarketing.util.Logger;
+import com.dotmarketing.util.UtilMethods;
+import com.dotcms.util.CollectionsUtils;
+```
+
+## Patterns
+- Config: `Config.getStringProperty("key", "default")` -- never System.getProperty.
+- Logging: `Logger.info(this, "msg")` -- never System.out.
+- Null: `UtilMethods.isSet(s)` before use.
+- APIs: `APILocator.getUserAPI()`, etc.
+- Exceptions: DotDataException, DotSecurityException.
+- Data classes: `@Value.Immutable` + builder.
+
+## Java
+- Core: Java 11 release compatibility. CLI: Java 21 ok. Runtime: Java 21. Migrating to Java 25 (parallel CI workflows validate forward compatibility).
+
+## Build
+```bash
+just build                           # full build (~8-15 min)
+just build-quicker                   # core only (~2-3 min)
+```
+
+## On-demand
+- `docs/backend/JAVA_STANDARDS.md`
+- `docs/backend/REST_API_PATTERNS.md`
+- `docs/backend/MAVEN_BUILD_SYSTEM.md`
+- `docs/backend/CONFIGURATION_PATTERNS.md`
+- `docs/backend/DATABASE_PATTERNS.md`

.claude/rules/maven-context.md

@@ -0,0 +1,29 @@
+---
+paths:
+  - "**/pom.xml"
+  - "bom/**/*"
+  - "parent/**/*"
+---
+
+# Maven Build System
+
+## Dependency management (CRITICAL)
+
+```
+parent/pom.xml              # Global properties, plugin management
+  bom/application/pom.xml   # Dependency management (ALL versions go here)
+    dotCMS/pom.xml           # Module dependencies (NO versions — inherited from BOM)
+```
+
+- **Versions** go ONLY in `bom/application/pom.xml` as properties + `<dependencyManagement>`.
+- **Dependencies** in `dotCMS/pom.xml` and other modules reference groupId:artifactId without `<version>`.
+- **Never** add a `<version>` tag directly in a module pom.xml.
+
+## Build commands
+```bash
+just build                     # full build (~8-15 min)
+just build-quicker             # core only (~2-3 min)
+```
+
+## On-demand
+- `docs/backend/MAVEN_BUILD_SYSTEM.md` -- full BOM patterns, plugin management, examples

.claude/rules/shell-cross-platform.md

@@ -0,0 +1,23 @@
+---
+paths:
+  - "justfile"
+  - "**/*.sh"
+  - ".config/wt.toml"
+  - "Makefile"
+  - "docker-compose*.yml"
+  - "Dockerfile*"
+---
+
+# Cross-platform Shell Compatibility
+
+All scripts, justfile recipes, and shell commands must work on **both macOS and Linux**.
+
+| Avoid | Use instead |
+|-------|-------------|
+| `lsof -ti :PORT` (macOS default) | `lsof` with fallback to `ss` or `fuser` |
+| `brew install ...` | document OS-conditional install paths |
+| `sed -i ''` (macOS BSD sed) | `sed -i` (GNU) -- test on both or use `perl -i` |
+| `/proc/` paths | avoid; not present on macOS |
+| `mktemp -t name` (BSD form) | `mktemp /tmp/name.XXXXXX` (POSIX, works on both) |
+
+When adding a new script or recipe, test or reason through both environments before committing.

.claude/rules/test-context.md

@@ -0,0 +1,39 @@
+---
+paths:
+  - "**/*.spec.ts"
+  - "**/*.test.ts"
+  - "**/test/**/*"
+  - "**/*Test.java"
+---
+
+# Testing Context
+
+## Frontend (Spectator)
+- Selectors: `byTestId('id')` only; never CSS classes for behavior.
+- Inputs: `spectator.setInput('prop', value)`; never `spectator.component.prop = value`.
+- CSS: `expect(el).toHaveClass('pi', 'pi-update')` (separate strings); not object form.
+- Test user flows: type, click, assert visible content; avoid testing internals or mock call counts.
+- **Mocks**: Use `@dotcms/utils-testing` createFake functions; never create manual mocks for domain objects.
+
+## data-testid
+- Component: `data-testid="user-profile"`. Controls: `user-profile-name-input`, `user-profile-save-button`. States: `loading-spinner`, `error-message`, `success-message`.
+
+## Backend (Java)
+- DotConnect for DB; APILocator for services. Structure: *Test.java (unit), *IT.java (integration).
+
+## Commands
+```bash
+# Backend (from repo root)
+just test-integration class=MyTestClass    # if alias exists, else:
+./mvnw -pl :dotcms-integration verify -Dcoreit.test.skip=false -Dit.test=MyTestClass
+
+# Frontend (Nx, from repo root)
+cd core-web && yarn nx run <project>:test
+cd core-web && yarn nx run <project>:test -t MyComponent
+```
+Replace `<project>` with the Nx project (e.g. `dotcms-ui`, `sdk-angular`, `edit-content`).
+
+## On-demand
+- `docs/frontend/TESTING_FRONTEND.md`
+- `docs/testing/BACKEND_UNIT_TESTS.md`
+- `docs/testing/INTEGRATION_TESTS.md`