chore(rules): update documentation structure and add new context files (#34428)

- Enhanced CLAUDE.md with clearer guidance on project rules and
documentation updates.
- Introduced new rule files for documentation maintenance, frontend
context, Java context, and testing context.
- Removed outdated documentation files to streamline the rules
directory.
- Updated README.md to reflect the new structure and provide an index
for easy navigation.

This update improves clarity and accessibility of project rules and
documentation practices.

Author: nicobytes

.cursor/rules/README.md

@@ -0,0 +1,28 @@
+# Cursor Project Rules
+
+Project rules live in `.cursor/rules/`. Cursor applies them according to the rule type.
+
+## Rule types (frontmatter)
+
+| Type in Cursor | Frontmatter | When it applies |
+|----------------|-------------|-----------------|
+| **Always Apply** | `alwaysApply: true` | On every chat |
+| **Apply to Specific Files** | `globs: ["..."]` + `alwaysApply: false` | When the open file/context matches the pattern |
+| **Apply Intelligently** | `description: "..."` + `alwaysApply: false` | When the Agent deems the description relevant |
+| **Apply Manually** | No alwaysApply/globs | Only if you mention the rule with @ (e.g. `@doc-updates`) |
+
+## Current rules
+
+- **dotcms-guide.mdc** – Always Apply. Navigation and critical reminders.
+- **frontend-context.mdc** – Globs: `core-web/**/*.{ts,tsx,html,scss,css}`. Nx monorepo, Angular, SDK, docs/frontend index.
+- **java-context.mdc** – Globs: `**/*.java`, `**/pom.xml`, `dotCMS/src/**/*`. Config, Logger, Maven.
+- **test-context.mdc** – Globs: `**/*.spec.ts`, `**/*Test.java`, etc. Spectator, data-testid.
+- **doc-updates.mdc** – Globs: `**/*.md`, `docs/**/*`. Where to update docs, DRY.
+
+## Best practices (Cursor docs)
+
+- Keep rules **short** (< 500 lines; ideally ~50 for reminders).
+- **One concern** per rule; split if they grow.
+- **Descriptions** that are clear and keyword-rich for Apply Intelligently.
+- Use **`.mdc`** (not `.md`) so Cursor interprets `description`, `globs`, `alwaysApply` correctly.
+- Put long details in **`/docs/`** and reference with `@docs/...` instead of copying into the rule.

.cursor/rules/doc-updates.mdc

@@ -0,0 +1,27 @@
+---
+description: "Where to update documentation. Use when editing docs/, CLAUDE.md, .md/.mdc files, or when adding patterns that should be documented."
+globs: ["**/*.md", "**/*.mdc", "CLAUDE.md", "docs/**/*"]
+alwaysApply: false
+---
+
+# Documentation Updates
+
+## Single source of truth
+- **CLAUDE.md** – navigation and quick reference only.
+- **`/docs/`** – full patterns by domain (backend, frontend, testing, etc.).
+- **`.cursor/rules/`** – short reminders and globs; link to `/docs/`, don’t duplicate.
+
+## 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`
+
+## When editing code
+- New Config usage → document in CONFIGURATION_PATTERNS.md.
+- New REST/API pattern → REST_API_PATTERNS.md.
+- New Angular/testing pattern → ANGULAR_STANDARDS.md or TESTING_FRONTEND.md.
+- Keep rules under ~50 lines; put details in `/docs/` and reference with `@docs/...`.
+
+## Quality
+- Use ✅/❌ examples. Cross-reference instead of duplicating. Same patterns for Claude and Cursor.

.cursor/rules/documentation-maintenance.md

@@ -0,0 +1,41 @@
+---
+description: dotCMS project navigation and critical reminders. Apply to every chat.
+alwaysApply: true
+---
+
+# dotCMS Development Guide
+
+## Primary Reference
+**CLAUDE.md** – main roadmap and quick patterns for both Claude and Cursor.
+
+## Project Structure
+
+```
+core/
+├── dotCMS/                    # Main backend Java code
+│   └── src/main/java/com/    # Java source files
+├── core-web/                  # Frontend (Angular/Nx monorepo)
+│   ├── apps/dotcms-ui/       # Main admin UI
+│   └── libs/                 # Shared libraries and SDKs
+├── dotcms-integration/        # Integration tests
+├── dotcms-postman/            # Postman API tests
+├── bom/application/pom.xml   # Dependency versions (ADD versions here)
+├── parent/pom.xml            # Plugin management
+└── .github/workflows/        # CI/CD pipelines
+```
+
+## Domain-Specific Rules (loaded by file pattern or relevance)
+- **Java / pom.xml**: `java-context.mdc` – Config, Logger, Maven, REST
+- **Frontend / core-web (Nx)**: `frontend-context.mdc` – Angular, SDK, Nx commands, links to docs/frontend
+- **Tests (*.spec.ts, *Test.java)**: `test-context.mdc` – Spectator, data-testid
+- **Docs (docs/, *.md)**: `doc-updates.mdc` – where to update, DRY
+
+## Critical Reminders
+- **Java**: Config/Logger only; never System.out or System.getProperty
+- **Maven**: Versions only in `bom/application/pom.xml`
+- **Angular**: @if/@for, input()/output(), spectator.setInput(), data-testid
+- **Security**: No secrets in code; validate input
+
+## Documentation
+- Update `/docs/` when you find gaps; keep rules short; single source of truth.
+- See `doc-updates.mdc` when editing docs or CLAUDE.md.

.cursor/rules/dotcms-guide.md

@@ -0,0 +1,47 @@
+---
+description: "Nx monorepo frontend (core-web): Angular, TypeScript, SDK Angular/React. Use when editing apps, libs, or SDK in core-web."
+globs: ["core-web/**/*.ts", "core-web/**/*.tsx", "core-web/**/*.html", "core-web/**/*.scss", "core-web/**/*.css"]
+alwaysApply: false
+---
+
+# 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/`**. Index: **`@docs/frontend/README.md`** — load it for the full doc list and when to use each; then load the specific doc you need.
+
+## Stack
+- **Angular**: standalone, signals, `inject()`, `input()`/`output()`, `@if`/`@for`, OnPush, PrimeNG/PrimeFlex.
+- **SDK**: `sdk-angular`, `sdk-react`, `sdk-client`, `sdk-types`, etc.
+- **Apps**: `dotcms-ui`, `content-drive-ui`, `edit-ema-ui`, portlets, libs.
+
+## Nx commands (repo root or `core-web`)
+```bash
+cd core-web && yarn nx show projects
+cd core-web && yarn nx run dotcms-ui:serve
+cd core-web && yarn nx run <project>:test
+cd core-web && yarn nx run <project>:test -t MyComponent
+cd core-web && yarn nx affected -t build --exclude='tag:skip:build'
+cd core-web && yarn nx affected -t lint --exclude='tag:skip:lint'
+cd core-web && yarn nx affected -t test --exclude='tag:skip:test'
+```
+
+## When to load which doc (`@docs/frontend/...`)
+
+| If you are… | Load |
+|-------------|------|
+| Writing or refactoring components, templates, or Angular patterns | `@docs/frontend/ANGULAR_STANDARDS.md` |
+| Defining component structure, inputs/outputs, file layout | `@docs/frontend/COMPONENT_ARCHITECTURE.md` |
+| Adding or changing feature state (stores, async) | `@docs/frontend/STATE_MANAGEMENT.md` |
+| Writing or updating styles, BEM, PrimeFlex | `@docs/frontend/STYLING_STANDARDS.md` |
+| Writing or fixing tests (Spectator, Jest, data-testid) | `@docs/frontend/TESTING_FRONTEND.md` |
+| Using TypeScript (strict, inference, `unknown`, `as const`, `#` private) | `@docs/frontend/TYPESCRIPT_STANDARDS.md` |
+
+**Reference in chat**: e.g. `@docs/frontend/ANGULAR_STANDARDS.md` or `@docs/frontend/TESTING_FRONTEND.md` so the right doc is included in context.
+
+## Quick reminders (details in docs)
+- **Angular**: `$` prefix for signals, `$` suffix for observables; no `standalone: true`; OnPush; `[class.x]` / `[style.x]` (no ngClass/ngStyle); host in `host: {}`.
+- **State**: Prefer NgRx Signal Store; avoid manual signal soup in components. See `@docs/frontend/STATE_MANAGEMENT.md`.
+- **Testing**: Spectator + Jest/Vitest; `byTestId()`, `spectator.setInput()`, `spectator.detectChanges()`, `spectator.click()`; never set component inputs directly. See `@docs/frontend/TESTING_FRONTEND.md`.
+- **TypeScript**: Strict types, no `any` (use `unknown`), `as const` instead of enums, `#` for private. See `@docs/frontend/TYPESCRIPT_STANDARDS.md`.
+
+## Nx
+For workspace/graph/config: Nx MCP tools or `yarn nx show projects`; see `core-web/AGENTS.md`.