diff --git a/.agents/README.md b/.agents/README.md
new file mode 100644
index 0000000000..a47c4b6c70
--- /dev/null
+++ b/.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
diff --git a/.agents/advanced.md b/.agents/advanced.md
new file mode 100644
index 0000000000..78f838b1d0
--- /dev/null
+++ b/.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/.
diff --git a/.agents/build.md b/.agents/build.md
new file mode 100644
index 0000000000..d0b48fdb70
--- /dev/null
+++ b/.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>`.
diff --git a/.agents/code-style.md b/.agents/code-style.md
new file mode 100644
index 0000000000..db9fe3fb65
--- /dev/null
+++ b/.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.
diff --git a/.agents/contributing.md b/.agents/contributing.md
new file mode 100644
index 0000000000..f5d25ed823
--- /dev/null
+++ b/.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.
diff --git a/.agents/git-workflow.md b/.agents/git-workflow.md
new file mode 100644
index 0000000000..e74c5f81aa
--- /dev/null
+++ b/.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)
+```
diff --git a/.agents/linting.md b/.agents/linting.md
new file mode 100644
index 0000000000..7804e73ff2
--- /dev/null
+++ b/.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
diff --git a/.agents/overview.md b/.agents/overview.md
new file mode 100644
index 0000000000..bee6c67a9e
--- /dev/null
+++ b/.agents/overview.md
@@ -0,0 +1,58 @@
+# Repository Overview
+
+**Type:** Large Nx-powered monorepo for the **Otter Framework**
+
+**Purpose:** Highly modular Angular-based framework and tooling to accelerate building Angular web apps:
+- Reusable Angular libraries (`packages/@o3r/*`, `@ama-sdk/*`, `@ama-openapi/*`, `@ama-mcp/*`, `@ama-mfe/*`, `@ama-styling/*`)
+- Dev tools (VS Code / Chrome extensions, GitHub Actions, CLIs, design tooling, OpenAPI tooling)
+- Showcase app (`apps/showcase`) and other apps
+
+**Main Tech Stack:**
+- Angular, TypeScript, RxJS, Redux-style patterns (NgRx)
+- Nx monorepo tooling
+- Jest for unit/integration tests, Vitest for type module packages' unit tests, Playwright for E2E
+- ESLint (flat config), Stylelint, Husky, lint-staged
+
+## Project Structure
+
+```
+├── apps/                              # Applications (showcase, extensions, etc.)
+├── packages/
+│   ├── @o3r/*                         # Core Otter framework libraries
+│   ├── @ama-sdk/*                     # SDK-related packages
+│   ├── @ama-openapi/*                 # OpenAPI tooling
+│   ├── @ama-styling/*                 # Styling/design tooling (figma-sdk, figma-extractor, style-dictionary)
+│   ├── @ama-mcp/*                     # MCP (Model Context Protocol) tooling
+│   ├── @ama-mfe/*                     # Micro-frontend utilities
+│   └── @o3r-training/*                # Training materials
+├── mcps/                              # MCP servers
+├── tools/
+│   ├── github-actions/*               # Local GitHub Actions
+│   └── @o3r/*                         # Internal build/test helpers
+├── docs/                              # Documentation organized by module
+└── migration-guides/                  # Version migration guides
+```
+
+## Package Scopes
+
+| Scope | Purpose | Angular-based |
+|-------|---------|---------------|
+| `@o3r/*` | Core Otter framework libraries | Yes |
+| `@ama-sdk/*` | SDK generation and client utilities | Partial |
+| `@ama-openapi/*` | OpenAPI tooling and CLI | No |
+| `@ama-styling/*` | Styling and design tooling | No |
+| `@ama-mcp/*` | MCP (Model Context Protocol) tooling | No |
+| `@ama-mfe/*` | Micro-frontend utilities | Yes |
+
+## Core Otter Modules
+
+- **@o3r/core**: Base framework, component architecture
+- **@o3r/components**: Component metadata and configuration
+- **@o3r/configuration**: Dynamic configuration system
+- **@o3r/localization**: i18n and translation management
+- **@o3r/styling**: Theming and CSS variables
+- **@o3r/rules-engine**: Business rules engine
+- **@o3r/store-sync**: NgRx store synchronization
+- **@o3r/apis-manager**: API call management
+- **@o3r/routing**: Enhanced routing capabilities
+- **@o3r/dynamic-content**: CMS integration
diff --git a/.agents/runtime.md b/.agents/runtime.md
new file mode 100644
index 0000000000..eb1af335b5
--- /dev/null
+++ b/.agents/runtime.md
@@ -0,0 +1,41 @@
+# Runtime Requirements
+
+**CRITICAL:** Always respect the runtime constraints declared in `package.json`.
+
+## Package Manager
+
+- **Package Manager:** Yarn 4.14.1 (Berry) with Plug'n'Play (PnP) enabled
+- **NEVER use `npm install` or `pnpm`** - Yarn Berry only
+- Version defined by `packageManager` field in root `package.json`
+
+## Node Version
+
+- **Node Version:** 22.17.0+ or 24.0.0+ (use LTS versions)
+- Version constraint in `engines.node` field in root `package.json`
+
+## Setup
+
+```bash
+# Install dependencies (always run first)
+yarn install
+
+# Optional: clear Nx cache when debugging
+yarn nx reset
+```
+
+## Working Behind Proxy
+
+If encountering SSL certificate issues with Yarn:
+- Set `NODE_EXTRA_CA_CERTS` environment variable to your certificate path
+- Or configure `httpsCertFilePath` in Yarn configuration
+
+## Parallel Execution
+
+To speed up builds/tests on multi-core machines:
+
+```bash
+# Set NX_PARALLEL environment variable
+yarn print:nx-parallel >> .env
+```
+
+This sets `NX_PARALLEL` to `cpus - 1` (minimum 2).
diff --git a/.agents/testing.md b/.agents/testing.md
new file mode 100644
index 0000000000..f443fdebe7
--- /dev/null
+++ b/.agents/testing.md
@@ -0,0 +1,69 @@
+# Testing Guidelines
+
+## Unit Tests
+
+```bash
+# Run all unit tests (MANDATORY before any PR)
+yarn test
+
+# Run tests for affected packages
+yarn test:affected
+
+# Run tests for specific package
+yarn nx test <package-name>
+
+# Run tests with coverage (CI mode)
+yarn nx test <package-name> --configuration=ci
+```
+
+### Test Framework Selection
+
+- **Use Jest** for CommonJS packages (packages without explicit type in package.json or not including .mts files)
+- **Use Vitest** for ES module packages (packages with `"type": "module"` in package.json or packages including .mts files)
+- **Use Playwright** for E2E tests
+
+### Test File Naming
+
+- Unit tests: `*.spec.ts` (co-located with source files)
+- Integration tests: `*.it.spec.ts`
+- Vitest tests: `*.test.ts`
+- E2E tests: Located in `e2e-playwright/` directories
+
+### Best Practices
+
+- **Add relevant unit tests** for all new code
+- **Test behavior, not implementation** - focus on what the code does, not how
+- **Use descriptive test names** - clearly state what is being tested
+- **Keep tests independent** - each test should be able to run in isolation
+- **Mock external dependencies** - use Jest/Vitest mocks for services, HTTP calls, etc.
+- **Co-locate tests** with source files (e.g., `foo.service.ts` and `foo.service.spec.ts`)
+
+## Integration Tests
+
+```bash
+# Run integration tests
+yarn test-int
+
+# Run integration tests for specific package
+yarn nx test-int <package-name>
+```
+
+Integration tests use Verdaccio (local npm registry) to test package publishing workflows.
+
+## E2E Tests
+
+```bash
+# Run E2E tests (Playwright)
+yarn test-e2e
+
+# Run E2E tests for specific package
+yarn nx test-e2e <package-name>
+```
+
+**Important:** E2E tests must pass before merging PRs. Check screenshot update process if visual tests fail (see `apps/showcase/scripts/update-screenshots/readme.md`).
+
+## VSCode Debugging
+
+The repository includes VSCode configuration:
+- Use `vscode-jest-tests` debugger task to debug unit tests with breakpoints
+- Launch configurations in `.vscode/launch.json`
diff --git a/.agents/tools.md b/.agents/tools.md
new file mode 100644
index 0000000000..0601959f4e
--- /dev/null
+++ b/.agents/tools.md
@@ -0,0 +1,49 @@
+# Development Tools
+
+## Verdaccio (Local NPM Registry)
+
+Used for integration testing and local package testing:
+
+```bash
+# Start Verdaccio in Docker
+yarn verdaccio:start
+
+# Start locally without Docker
+yarn verdaccio:start-local
+
+# Publish all packages to local registry
+yarn verdaccio:publish
+
+# Stop Verdaccio
+yarn verdaccio:stop
+
+# Clean Verdaccio storage
+yarn verdaccio:clean
+```
+
+Verdaccio configuration is in `.verdaccio/conf/`.
+
+## Documentation Generation
+
+```bash
+# Generate all documentation
+yarn doc:generate
+
+# Generate root documentation
+yarn doc:root
+
+# Generate package-specific documentation
+yarn doc:packages
+
+# Generate specific package documentation
+yarn nx documentation <package-name>
+```
+
+Documentation is generated using Compodoc and output to `generated-doc/`.
+
+## VSCode Integration
+
+The repository includes VSCode configuration:
+- Recommended extensions in `.vscode/extensions.json`
+- Launch configurations for debugging in `.vscode/launch.json`
+- Use `vscode-jest-tests` debugger task to debug unit tests with breakpoints
diff --git a/.vscode/settings.json b/.vscode/settings.json
index 447ff881c1..86f66946ef 100644
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -49,7 +49,7 @@
     "jest.config.js": "jest.config.*",
     "nx.json": ".nxignore",
     "package.json": "ng-package.json, project.json, yarn.lock, .yarnrc.yml, .npmrc, .npmrc.*, .pnp.*",
-    "readme.md": "security.md, code_of_conduct.md, contributing.md",
+    "readme.md": "security.md, code_of_conduct.md, contributing.md, agents.md",
     "tsconfig.base.json": "tsconfig.*.json",
     "tsconfig.json": "tsconfig.*.json"
   },
diff --git a/.windsurf/rules/code-style-typescript.md b/.windsurf/rules/code-style-typescript.md
deleted file mode 100644
index 434f7d7b0a..0000000000
--- a/.windsurf/rules/code-style-typescript.md
+++ /dev/null
@@ -1,31 +0,0 @@
----
-trigger: glob
-globs: **/*.ts
----
-
-# Otter Framework - TypeScript/JavaScript Code Style
-
-## General Formatting
-
-All formatting rules (charset, indentation, line endings, etc.) are defined in `.editorconfig` at the repository root. Refer to that file for the configuration.
-
-## TypeScript / JavaScript Conventions
-
-- **Always write JSDoc comments** for methods and properties using `/** ... */` pattern
-- **Properties must have the most restricted type possible**:
-  ```typescript
-  // Bad
-  private type: string;
-
-  // Good
-  private type: 'A' | 'B';
-  ```
-- **Imports must be at the top of the file** - never in the middle of code
-- **Follow existing ESLint rules** defined in `packages/@o3r/eslint-config`
-- **Use `const` by default**, `let` only when reassignment is needed, never `var`
-
-## File Organization
-
-- **One class/interface per file** when possible
-- **Keep files focused** - split large files into smaller, focused modules
-- **Co-locate tests** with source files (e.g., `foo.service.ts` and `foo.service.spec.ts`)
\ No newline at end of file
diff --git a/.windsurf/rules/commands.md b/.windsurf/rules/commands.md
deleted file mode 100644
index e640ea258e..0000000000
--- a/.windsurf/rules/commands.md
+++ /dev/null
@@ -1,44 +0,0 @@
----
-trigger: always_on
----
-
-# Otter Framework - Commands
-
-## Build
-
-```bash
-yarn build          # Full build (includes TS and JAR targets)
-yarn build:ts       # TypeScript-only build (preferred for local dev)
-```
-
-## Lint
-
-```bash
-yarn lint           # Full lint (mandatory before any PR)
-```
-
-## Tests
-
-```bash
-yarn test           # Unit tests (mandatory before any PR)
-yarn test-e2e       # E2E tests (Playwright)
-yarn test-int       # Integration tests (requires Verdaccio)
-```
-
-## Per-project commands (Nx)
-
-```bash
-yarn nx build <project>
-yarn nx lint <project>
-yarn nx test <project>
-```
-
-## Validation Workflow
-
-Before considering changes complete, always run:
-
-```bash
-yarn build      # Full build
-yarn lint       # Linting
-yarn test       # Unit tests
-```
diff --git a/.windsurf/rules/documentation.md b/.windsurf/rules/documentation.md
deleted file mode 100644
index 1735e67ced..0000000000
--- a/.windsurf/rules/documentation.md
+++ /dev/null
@@ -1,26 +0,0 @@
----
-trigger: always_on
----
-
-# Otter Framework - Documentation Requirements
-
-## Code Documentation
-
-- **Always write description comments** for exported constants, variables, functions, public classes, methods and properties
-- **Use JSDoc format**: `/** Your comment */`
-- **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%)
- * @deprecated Will be removed in v15. Use `calculatePriceWithTax()` instead.
- */
-public calculateTotal(basePrice: number, taxRate: number): number {
-  return basePrice * (1 + taxRate);
-}
-```
\ No newline at end of file
diff --git a/.windsurf/rules/git-ci.md b/.windsurf/rules/git-ci.md
deleted file mode 100644
index 8b890e5e7a..0000000000
--- a/.windsurf/rules/git-ci.md
+++ /dev/null
@@ -1,29 +0,0 @@
----
-trigger: always_on
----
-
-# Otter Framework - Git & CI
-
-## Commit Message Format
-
-Follow [Conventional Commits](https://www.conventionalcommits.org/). Allowed types are defined in `commitlint.config.cts`.
-
-```bash
-# Examples
-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** (from `commitlint.config.cts`):
-- Header max length: **100 characters**
-- Subject must not be empty or end with a period
-- Type and scope must be lowercase
-
-## CI Contract - Do Not Break
-
-- **All required CI jobs must remain green**: build, lint, unit tests, IT tests, E2E tests
-- **Do not modify CI workflows** (`.github/workflows/*`) unless explicitly requested
-- **Do not touch release/versioning/publish flows**: `GitVersion.yml`, `release.yml`, `publish.yml`
-- **All changes must go through Pull Requests** - never publish directly
diff --git a/.windsurf/rules/project-structure.md b/.windsurf/rules/project-structure.md
deleted file mode 100644
index a84ce7e269..0000000000
--- a/.windsurf/rules/project-structure.md
+++ /dev/null
@@ -1,38 +0,0 @@
----
-trigger: always_on
----
-
-# Otter Framework - Project Structure Reference
-
-## Directory Layout
-
-```
-├── apps/                              # Applications (showcase, extensions, etc.)
-├── packages/
-│   ├── @o3r/*                         # Core Otter framework libraries
-│   ├── @ama-sdk/*                     # SDK-related packages
-│   ├── @ama-openapi/*                 # OpenAPI tooling
-│   ├── @ama-styling/*                 # Styling/design tooling
-│   ├── @ama-mcp/*                     # MCP tooling
-│   └── @ama-mfe/*                     # Micro-frontend utilities
-├── tools/
-│   ├── github-actions/*               # Local GitHub Actions
-│   └── @o3r/*                         # Internal build/test helpers
-├── docs/                              # Documentation
-└── migration-guides/                  # Version migration guides
-```
-
-## Package Scopes
-
-| Scope | Purpose | Angular |
-|-------|---------|---------|
-| `@o3r/*` | Core Otter framework libraries | Yes |
-| `@ama-sdk/*` | SDK generation and client utilities | Partial |
-| `@ama-openapi/*` | OpenAPI tooling and CLI | No |
-| `@ama-styling/*` | Styling and design tooling | No |
-| `@ama-mcp/*` | MCP (Model Context Protocol) tooling | No |
-| `@ama-mfe/*` | Micro-frontend utilities | Yes |
-
-## Additional Resources
-
-- [CONTRIBUTING.md](./CONTRIBUTING.md) - Full contribution guidelines
\ No newline at end of file
diff --git a/.windsurf/rules/repository-overview.md b/.windsurf/rules/repository-overview.md
deleted file mode 100644
index 55baea3e8c..0000000000
--- a/.windsurf/rules/repository-overview.md
+++ /dev/null
@@ -1,27 +0,0 @@
----
-trigger: always_on
----
-
-# Otter Framework - Repository Overview
-
-## Type
-
-Large Nx-powered monorepo for the **Otter Framework**
-
-## Purpose
-
-Highly modular Angular-based framework and tooling to accelerate building Angular web apps:
-- Reusable Angular libraries (`packages/@o3r/*`, `@ama-sdk/*`, `@ama-openapi/*`, `@ama-mcp/*`, `@ama-mfe/*`, `@ama-styling/*`)
-- Dev tools (VS Code / Chrome extensions, GitHub Actions, CLIs, design tooling, OpenAPI tooling)
-- Showcase app (`apps/showcase`) and other apps
-
-## Main Tech Stack
-
-- Angular, TypeScript, RxJS, Redux-style patterns
-- Nx monorepo tooling
-- Jest for unit/integration tests, Vitest for the type module packages' unit tests, Playwright for e2e
-- ESLint (flat config), Stylelint, Husky, lint-staged
-
-## Layout
-
-Root monorepo with `apps/`, `packages/`, and `tools/` as main code roots
diff --git a/.windsurf/rules/runtime-setup.md b/.windsurf/rules/runtime-setup.md
deleted file mode 100644
index 9f6b66ccb5..0000000000
--- a/.windsurf/rules/runtime-setup.md
+++ /dev/null
@@ -1,24 +0,0 @@
----
-trigger: always_on
----
-
-# Otter Framework - Runtime & Setup
-
-## Runtime Requirements
-
-**Always respect the runtime constraints declared in `package.json`.**
-
-- **Node.js**: Use a version satisfying `engines.node` field in root `package.json`
-- **Yarn**: Use Yarn Berry **Never use `npm install` or `pnpm`** (version defined by `packageManager` field in root `package.json`)
-
-## Setup and Bootstrap
-
-From repo root:
-
-```bash
-# Install dependencies (always first)
-yarn install
-
-# Optional: clear Nx cache when debugging
-yarn nx reset
-```
diff --git a/.windsurf/rules/testing.md b/.windsurf/rules/testing.md
deleted file mode 100644
index 1aaaaa5414..0000000000
--- a/.windsurf/rules/testing.md
+++ /dev/null
@@ -1,29 +0,0 @@
----
-trigger: always_on
----
-
-# Otter Framework - Testing Requirements
-
-## General Testing Guidelines
-
-- **Add relevant unit tests** for all new code
-- **E2E tests must pass** - check screenshot update process if visual tests fail
-- **Follow existing test patterns** in the codebase
-
-## Test Frameworks
-
-- **Use Jest** for unit tests of type commonjs packages (e.g. packages without explicit type in package.json or not including .mts files)
-- **Use Vitest** for unit tests of type module packages (e.g. packages with explicit type "module" in package.json or packages including .mts files)
-- **Use Playwright** for e2e tests
-
-## Test File Naming
-
-- Unit tests: `*.spec.ts` (co-located with source files)
-- E2E tests: Located in `e2e-playwright/` directories
-
-## Best Practices
-
-- **Test behavior, not implementation** - focus on what the code does, not how
-- **Use descriptive test names** - clearly state what is being tested
-- **Keep tests independent** - each test should be able to run in isolation
-- **Mock external dependencies** - use Jest mocks for services, HTTP calls, etc.
diff --git a/.windsurf/workflows/commit-and-push-code-to-github.md b/.windsurf/workflows/commit-and-push-code-to-github.md
deleted file mode 100644
index e54e55236c..0000000000
--- a/.windsurf/workflows/commit-and-push-code-to-github.md
+++ /dev/null
@@ -1,54 +0,0 @@
----
-description: Workflow to commit and push a branch for a pull request
----
-
-1. **Validate code**
-   - Run `/validate-code` workflow
-   - If any command fails with blocking errors: suggest fixes without modifying code, then **STOP**
-   - Skipped steps are not blocking
-
-2. **Validate branch**
-   - Run: `git branch --show-current`
-   - If on `main` or `release/*`: suggest a new branch name (`feat/`, `fix/`, or `chore/`) and present command: `git switch -c <branch-name>`
-   - If user chooses to remain on `main` or `release/*` after the suggestion:
-     - Log: "⚠️ Workflow stopped: Cannot commit or push directly to protected branch `<branch-name>`. Please create a new branch to continue."
-     - **STOP** - workflow cannot continue on protected branches
-   - Otherwise, continue
-
-3. **Determine commit strategy**
-   - Run these commands to gather context:
-     ```
-     git log -1 --oneline
-     git rev-parse --abbrev-ref --symbolic-full-name @{upstream} 2>/dev/null || echo "No upstream"
-     git branch -r --contains HEAD 2>/dev/null
-     git status --short
-     ```
-   - **Amend** if:
-     - Current commit is NOT on the upstream branch, OR
-     - Staged files overlap with files modified in the previous commit and appear to be related changes
-   - **New commit** if:
-     - Current commit already exists on upstream, OR
-     - No prior commit exists, OR
-     - Changes are unrelated to the previous commit
-   - Announce decision clearly with reasoning
-   - **DO NOT** create the commit yet - only decide the strategy
-
-4. **Stage files**
-   - Show current status: `git status --short`
-   - Propose a `git add` command with the files to stage (user can approve or modify)
-
-5. **Create commit**
-   - Based on the strategy determined in step 3:
-     - If **amend**: `git commit --amend --no-edit` (or with new message if needed)
-     - If **new commit**: Create a concise conventional commit message following commitlint.config.cts:
-       - Format: `[type]: concise description`
-       - Types: `fix`, `feat`, `docs`, `chore`, etc.
-       - Example: `feat(tools): add Windsurf workflows`
-       - Run: `git commit -m "<message>"`
-
-6. **Push to remote**
-   - Based on the commit strategy from step 3:
-     - If **amended commit**: `git push --force-with-lease`
-     - If **new commit**:
-       - First push (no upstream): `git push -u origin $(git branch --show-current)`
-       - Subsequent pushes: `git push`
\ No newline at end of file
diff --git a/.windsurf/workflows/validate-code.md b/.windsurf/workflows/validate-code.md
deleted file mode 100644
index b8fa306b3e..0000000000
--- a/.windsurf/workflows/validate-code.md
+++ /dev/null
@@ -1,17 +0,0 @@
----
-description: Workflow to prepare and validate code
-auto_execution_mode: 1
----
-
-# Commands to run
-
-// turbo
-1. **Install dependencies**
-   - Run dependency installation from the repo root: `yarn install`
-
-// turbo
-2. **Run full build, lint, and tests**
-   - Run the full build, lint, and tests (in parallel):
-     - `yarn build`
-     - `yarn lint:affected`
-     - `yarn test:affected`
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000000..59b00fb859
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,100 @@
+# AGENTS.md
+
+This file provides guidance to AI coding agents when working with code in this repository.
+
+Following the [agents.md](https://github.com/agentsmd/agents.md) specification for cross-LLM compatibility.
+
+---
+
+## Quick Start
+
+**Type:** Large Nx-powered monorepo for the **Otter Framework** - Angular-based framework and tooling
+
+**Essential Commands:**
+
+```bash
+yarn install        # Install dependencies (always first)
+yarn build          # Build all packages
+yarn lint           # Lint (mandatory before PR)
+yarn test           # Unit tests (mandatory before PR)
+```
+
+**Package Manager:** Yarn 4.14.1 (Berry) with PnP - **NEVER use npm or pnpm**
+**Node Version:** 22.17.0+ or 24.0.0+
+
+---
+
+## Context Files
+
+Detailed documentation is split into context-specific files in `.agents/` to reduce token usage. Load only what you need for your current task:
+
+### Always Relevant
+
+- **[overview.md](./.agents/overview.md)** - Repository structure, tech stack, and package scopes
+
+### Task-Specific Context
+
+**Building & Development:**
+
+- **[build.md](./.agents/build.md)** - Build system, commands, and Nx targets
+- **[runtime.md](./.agents/runtime.md)** - Runtime requirements and setup
+
+**Code Quality:**
+
+- **[testing.md](./.agents/testing.md)** - Unit, integration, and E2E testing guidelines
+- **[linting.md](./.agents/linting.md)** - ESLint configuration and linting commands
+- **[code-style.md](./.agents/code-style.md)** - TypeScript conventions, JSDoc, and best practices
+
+**Version Control:**
+
+- **[git-workflow.md](./.agents/git-workflow.md)** - Git workflow, commit messages, protected branches, and CI/CD rules
+
+**Contributing:**
+
+- **[contributing.md](./.agents/contributing.md)** - Contribution rules, PR process, and quality requirements
+
+**Advanced Features:**
+
+- **[advanced.md](./.agents/advanced.md)** - Otter-specific concepts, metadata extraction, core modules
+- **[tools.md](./.agents/tools.md)** - Verdaccio, documentation generation, VSCode integration
+
+---
+
+## Critical Rules
+
+**NEVER:**
+
+- Use `npm install` or `pnpm` - Yarn Berry only
+- Commit directly to `main` or `release/*` branches
+- Modify CI workflows (`.github/workflows/*`) unless explicitly requested
+- Skip linting or testing before submitting PRs
+
+**ALWAYS:**
+
+- Run `yarn build && yarn lint && yarn test` before considering changes complete
+- Write JSDoc comments for exported functions, classes, methods, and properties
+- Add unit tests for new code
+- Use conventional commit messages (see [git-workflow.md](./.agents/git-workflow.md))
+- Use the most restricted type possible for TypeScript properties
+
+---
+
+## Framework Versions
+
+- Angular: ~21.2.4
+- TypeScript: ~5.9.2
+- RxJS: ^7.8.1
+- NgRx: ~21.1.0
+- Nx: ~22.7.0
+
+---
+
+## About This File
+
+This AGENTS.md follows the [agents.md](https://github.com/agentsmd/agents.md) specification. Context is split into separate files in `.agents/` to optimize token usage - load only what you need for your current task.
+
+**Maintaining:**
+
+- Update context files when build commands, structure, or workflows change
+- Keep versions up-to-date
+- AI agents with edit permissions can maintain these files
diff --git a/README.md b/README.md
index 0a8646b0f6..ee8961493b 100644
--- a/README.md
+++ b/README.md
@@ -51,6 +51,12 @@ npm create @o3r my-project
 
 Please read the [Contributing](./CONTRIBUTING.md) file for details on our code of conduct and the process to submit pull requests.
 
+## AI Coding Agents
+
+This repository includes an [AGENTS.md](./AGENTS.md) file that provides context for AI coding assistants (Claude Code, GitHub Copilot, Cursor, Windsurf, etc.). 
+
+The documentation is split into focused context files in [`.agents/`](./.agents/) to optimize token usage - AI agents load only what they need for their current task (testing, building, committing, etc.), reducing token consumption by 50-60% compared to a single large file.
+
 ## Versioning
 
 Please refer to [Security file](./SECURITY.md).