feat: create Agents.md and deprecate windsurf specific document

.agents/README.md

@@ -0,0 +1,66 @@
+# AI Agent Context Files
+
+This directory contains context-specific documentation for AI coding agents, split by task type to optimize token usage.
+
+## Structure
+
+The main `AGENTS.md` file in the repository root provides a quick start guide and references these detailed context files. AI agents should:
+
+1. Always read `AGENTS.md` first (lightweight, ~100 lines)
+2. Load only the specific context files needed for their current task
+
+## Context Files
+
+### Always Relevant
+- **`overview.md`** - Repository structure, tech stack, and package scopes
+
+### Task-Specific Context
+
+**Building & Development:**
+- **`build.md`** - Build system, commands, and Nx targets (~60 lines)
+- **`runtime.md`** - Runtime requirements and setup (~40 lines)
+
+**Code Quality:**
+- **`testing.md`** - Unit, integration, and E2E testing guidelines (~80 lines)
+- **`linting.md`** - ESLint configuration and linting commands (~30 lines)
+- **`code-style.md`** - TypeScript conventions, JSDoc, and best practices (~50 lines)
+
+**Version Control:**
+- **`git-workflow.md`** - Git workflow, commit messages, protected branches, and CI/CD rules (~70 lines)
+
+**Contributing:**
+- **`contributing.md`** - Contribution rules, PR process, and quality requirements (~40 lines)
+
+**Advanced Features:**
+- **`advanced.md`** - Otter-specific concepts, metadata extraction, core modules (~30 lines)
+- **`tools.md`** - Verdaccio, documentation generation, VSCode integration (~50 lines)
+
+## Benefits of This Approach
+
+- **Reduced Token Usage:** Load only relevant context (typical: 100-200 lines vs full 500+ line file)
+- **Faster Processing:** Less content to parse per interaction
+- **Better Focus:** AI agents get precisely the information they need
+- **Easier Maintenance:** Update specific sections without affecting others
+- **Scalability:** Easy to add new context files as the project grows
+
+## Usage Examples
+
+**Example 1: Writing Tests**
+Load: `AGENTS.md` + `testing.md` + `code-style.md` (~230 lines)
+
+**Example 2: Building Code**
+Load: `AGENTS.md` + `build.md` + `runtime.md` (~200 lines)
+
+**Example 3: Creating PR**
+Load: `AGENTS.md` + `git-workflow.md` + `contributing.md` (~210 lines)
+
+**Example 4: Full Context**
+Load all files (~600 lines total, still better organized than one large file)
+
+## Maintaining These Files
+
+- Keep files focused on their specific domain
+- Update when significant changes occur in that domain
+- Keep consistent formatting across all files
+- Link to main repository docs (CONTRIBUTING.md, etc.) for additional details
+- AI agents with edit permissions can update these files as they discover changes

.agents/advanced.md

@@ -0,0 +1,22 @@
+# Advanced Otter Features
+
+## Metadata Extraction
+
+Otter can extract metadata from Angular applications for CMS integration:
+
+- Configuration metadata: `extract-components`
+- Translation keys: `extract-translations`
+- Styling metadata: `extract-style`
+- Rules engine metadata: `extract-rules-engine`
+
+## Framework Versions
+
+- Angular: ~21.2.4
+- TypeScript: ~5.9.2
+- RxJS: ^7.8.1
+- NgRx: ~21.1.0
+- Nx: ~22.7.0
+
+## Showcase Application
+
+The `apps/showcase` directory contains a demonstration application showcasing Otter features. It's deployed to GitHub Pages and accessible at https://amadeusitgroup.github.io/otter/.

.agents/build.md

@@ -0,0 +1,68 @@
+# Build System
+
+This project uses Nx for task orchestration with extensive caching.
+
+## Build Commands
+
+```bash
+# Build all packages (includes TypeScript and JAR if applicable)
+yarn build
+
+# Build TypeScript only (faster, excludes JAR)
+yarn build:ts
+
+# Build specific package
+yarn nx build <package-name>
+
+# Build affected packages only
+yarn build:affected
+
+# Build tools needed after install
+yarn build:tools
+```
+
+## Build Targets
+
+Packages may have multiple build targets depending on their type:
+
+- `compile` - TypeScript compilation
+- `build-builders` - Angular builders/schematics
+- `build-cli` - CLI tools
+- `build-fixtures` - Test fixtures
+- `expose-templates` - Copy schematic templates
+- `expose-schemas` - Copy JSON schemas
+- `prepare-build-builders` - Prepare builder metadata
+
+Results are output to each package's `dist/` directory (`packages/@<scope>/<name>/dist`).
+
+## Nx Cache Management
+
+Nx caches build, test, and lint outputs. To clear the cache:
+
+```bash
+yarn nx reset
+```
+
+Use this when investigating issues or when cache seems stale.
+
+## Development Workflow
+
+### Creating New Packages
+
+```bash
+# Create a new scope
+yarn create:scope <scope-name>
+
+# Create a new library in a scope
+yarn ng g library @<scope-name>/<library-name>
+```
+
+## Schematics and Builders
+
+Many packages include Angular schematics and builders:
+- Schematics: code generators for Angular CLI
+- Builders: custom build/test/lint executors for Angular CLI
+- Templates: located in `schematics/*/templates/` or `builders/*/templates/`
+- Schemas: JSON schemas in `schemas/` directory
+
+To work on schematics/builders, build with `yarn nx build-builders <package-name>`.

.agents/code-style.md

@@ -0,0 +1,53 @@
+# Code Style Guidelines
+
+## General Formatting
+
+All formatting rules (charset, indentation, line endings, etc.) are defined in `.editorconfig` at the repository root.
+
+## TypeScript/JavaScript Conventions
+
+### Documentation
+
+- **Always write JSDoc comments** for exported constants, variables, functions, public classes, methods and properties
+- Use `/** ... */` pattern
+- Document parameters and return types for complex functions
+- Add `@deprecated` tag when deprecating code, mentioning the major version for removal
+
+**Example:**
+
+```typescript
+/**
+ * Calculates the total price including tax.
+ * @param basePrice The base price before tax
+ * @param taxRate The tax rate as a decimal (e.g., 0.2 for 20%)
+ * @returns The total price with tax applied
+ * @deprecated Will be removed in v15. Use `calculatePriceWithTax()` instead.
+ */
+public calculateTotal(basePrice: number, taxRate: number): number {
+  return basePrice * (1 + taxRate);
+}
+```
+
+### Type Safety
+
+**Properties must have the most restricted type possible:**
+
+```typescript
+// ❌ Bad
+private type: string;
+
+// ✅ Good
+private type: 'A' | 'B';
+```
+
+### Best Practices
+
+- **Use `const` by default**, `let` only when reassignment is needed, never `var`
+- **Imports must be at the top of the file** - never in the middle of code
+- **One class/interface per file** when possible
+- **Keep files focused** - split large files into smaller, focused modules
+- **Follow existing ESLint rules** defined in `packages/@o3r/eslint-config`
+
+## Experimental APIs
+
+APIs marked with `@experimental` JSDoc tag are unstable and may change without warning. When using experimental APIs, pin package versions explicitly.

.agents/contributing.md

@@ -0,0 +1,31 @@
+# Contributing Rules
+
+## For Minor Versions
+
+- **Make only non-breaking changes**
+- Enhancements to existing code are possible - discuss beforehand with the Otter team via a feature request
+- If replacing an existing feature, **deprecate the old code** in minor versions
+  - Add `@deprecated` tag in JSDoc
+  - Mention the major version when it will be removed
+  - Note: Only **even** major Otter versions allow **costly breaking changes**
+  - A breaking change can be effective only from major version `n + 2` **after the deprecation**
+
+## Quality Requirements
+
+- Linter tasks must pass
+- Add relevant unit tests
+- E2E tests must pass (check screenshot update process if visual tests fail)
+- Any change should be followed by changes in the generator whenever applicable
+- Properties should have the most restricted type possible
+- Always write description comments for methods and properties
+
+## PR Review Process
+
+- All PRs require approval from the Otter team (@AmadeusITGroup/otter_admins)
+- Link corresponding issue in PR description
+- Follow the PR template
+- Ensure all CI checks pass
+
+## Additional Resources
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for complete contribution guidelines.

.agents/git-workflow.md

@@ -0,0 +1,64 @@
+# Git Workflow and CI/CD
+
+## Protected Branches
+
+- `main` - main development branch
+- `release/*` - release branches
+
+**Never commit or push directly to these branches.** Always create a feature branch:
+
+- `feat/*` - for new features
+- `fix/*` - for bug fixes
+- `chore/*` - for maintenance tasks
+
+## Commit Message Format
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/). Rules are defined in `commitlint.config.cts`.
+
+**Format:** `[type]([scope]): concise description`
+
+**Examples:**
+
+```bash
+git commit -m "fix: correct null check in service"
+git commit -m "feat(core): add new validation helper"
+git commit -m "docs: update API documentation"
+git commit -m "refactor!: rename config options"  # Breaking change
+```
+
+**Rules:**
+
+- Header max length: **100 characters**
+- Subject must not be empty or end with a period
+- Type and scope must be lowercase
+- Common types: `fix`, `feat`, `docs`, `chore`, `refactor`, `test`, `build`, `ci`
+- Breaking changes: add `!` after type/scope OR include `breaking` in message
+
+## Versioning
+
+```bash
+# Set version for all packages
+yarn set:version <version>
+
+# Harmonize versions across package.json files
+yarn harmonize:version
+```
+
+## CI Contract - Do Not Break
+
+**CRITICAL:** The following must always remain green:
+
+- All required CI jobs: build, lint, unit tests, integration tests, E2E tests
+- **Never modify CI workflows** (`.github/workflows/*`) unless explicitly requested
+- **Never touch release/versioning/publish flows**: `GitVersion.yml`, release.yml, publish.yml
+- **All changes must go through Pull Requests** - never commit directly to main/release branches
+
+## Validation Workflow Before PR
+
+Before considering changes complete, always run:
+
+```bash
+yarn build      # Full build (mandatory)
+yarn lint       # Linting (mandatory)
+yarn test       # Unit tests (mandatory)
+```

.agents/linting.md

@@ -0,0 +1,34 @@
+# Linting
+
+```bash
+# Lint all packages (MANDATORY before any PR)
+yarn lint
+
+# Lint affected packages
+yarn lint:affected
+
+# Lint specific package
+yarn nx lint <package-name>
+
+# Lint with cache (CI mode)
+yarn nx lint <package-name> --configuration=ci
+
+# Lint project.json files
+yarn lint:project-json
+```
+
+## Configuration
+
+The project uses ESLint with flat config (`eslint.config.mjs`).
+
+**Configuration files:**
+- Root: `eslint.config.mjs`, `eslint.shared.config.mjs`, `eslint.local.config.mjs`
+- Package-specific: `packages/@o3r/eslint-config/`, `packages/@o3r/eslint-plugin/`
+
+**Linter tasks must pass before submitting PRs.**
+
+## Husky Git Hooks
+
+The project uses Husky for git hooks:
+- Pre-commit: runs lint-staged (ESLint, editorconfig-checker)
+- Commit message validation: uses commitlint with conventional commits