docs(ai): add coding style and tools docs to guide AI-assisted development

.ai-doc/00-index.md

@@ -0,0 +1,63 @@
+---
+title: OVHcloud Manager — Documentation Overview
+last_update: 2025-01-27
+tags: [overview, architecture, best-practices, ovhcloud, manager]
+ai: true
+---
+
+# OVHcloud Manager — Documentation Overview
+
+This documentation set provides a **structured and unified knowledge base** for the OVHcloud Manager ecosystem.
+It is designed to be easily readable by humans and consumable by AI systems to support automation, migration, and continuous improvement processes.
+
+---
+
+## 🧭 Purpose
+
+The goal of this documentation is to:
+- Describe the **technical architecture** and µApp containerization model used in the Manager.
+- Define **frontend coding standards** and reusable design patterns.
+- Document **ODS and MRC component systems** for UI consistency.
+- Detail **GitHub workflows** and review processes for collaborative development.
+- Clarify **testing strategies** to ensure quality and maintainability.
+- Provide **references and templates** for developers and automation tools.
+- Support **AI-assisted migration** from AngularJS to React with comprehensive patterns and guidelines.
+
+---
+
+## 📂 Structure Overview
+
+| Folder | Description |
+|--------|--------------|
+| `_doc-template.md` | Template used for new documentation files. |
+| `_references.md` | Unified human + machine list of all external documentation and source URLs. |
+| `00-index.md` | This file — serves as the main entry point. |
+| `10-architecture/` | Explains Manager architecture, APIs, µApp containerization, module integration, and related commands. Includes [`react-uapp-blueprint.md`](./10-architecture/react-uapp-blueprint.md), [`react-tracking.md`](./10-architecture/react-tracking.md), [`data-fetching.md`](./10-architecture/data-fetching.md), [`feature-flipping.md`](./10-architecture/feature-flipping.md), [`common-translations.md`](./10-architecture/common-translations.md), [`app-folder-structure.md`](./10-architecture/app-folder-structure.md), [`uapp-containerization.md`](./10-architecture/uapp-containerization.md), [`api-overview.md`](./10-architecture/api-overview.md). |
+| `20-dependencies/` | Documents ODS and MRC component libraries, module integrations, and external dependencies. Includes Manager packages (`manager-core-api.md`, `manager-react-shell-client.md`, `manager-react-core-application.md`, `manager-core-utils.md`, `manager-config.md`, `manager-static-analysis-kit.md`, `manager-vite-config.md`, `request-tagger.md`, `shell.md`), external libraries (`react-router-dom.md`, `tanstack-react-query.md`, `react-i18next.md`, `tailwind-css.md`), ODS components (`ods-components.md`, `ods-themes.md`), MRC components (`mrc-components.md`), and module integrations (`logs-to-customer-module.md`). |
+| `30-best-practices/` | Contains coding conventions, frontend design patterns, React best practices, migration patterns, and accessibility testing. Includes [`development-standards.md`](./30-best-practices/development-standards.md), [`frontend-design-patterns.md`](./30-best-practices/frontend-design-patterns.md), [`frontend-react-patterns.md`](./30-best-practices/frontend-react-patterns.md), [`react-best-practices.md`](./30-best-practices/react-best-practices.md), [`typescript-cheatsheet.md`](./30-best-practices/typescript-cheatsheet.md), [`html-accessibility-testing.md`](./30-best-practices/html-accessibility-testing.md), [`migration-guide.md`](./30-best-practices/migration-guide.md). |
+| `40-workflow/` | Describes branching, commit, and review processes. Includes [`branching-and-commits.md`](./40-workflow/branching-and-commits.md), [`review-and-improvement.md`](./40-workflow/review-and-improvement.md). |
+
+---
+
+## 🧩 Usage Guidelines
+
+- Each `.md` file is **self-contained** with its own frontmatter metadata.
+- External references should point to entries listed in `_references.md`.
+- Follow naming conventions and folder structure to ensure consistency.
+- Use `_doc-template.md` for new documents to ensure proper formatting.
+- Keep examples concise and reusable.
+
+---
+
+## 🧠 AI Integration
+
+This documentation supports **AI-assisted automation** and contextual ingestion:
+- Files are atomic and semantically organized.
+- Metadata fields (`title`, `tags`, `ai`) allow AI tools to filter and prioritize information.
+- YAML and Markdown formats are minimal and standardized for reliable parsing.
+
+---
+
+## 🔗 References
+
+For the complete list of external documentation, see [`_references.md`](./_references.md).

.ai-doc/10-architecture/api-overview.md

@@ -0,0 +1,49 @@
+---
+title: OVHcloud API Overview
+last_update: 2025-10-13
+tags: [api, overview, ovhcloud, architecture]
+ai: true
+---
+
+# OVHcloud API Overview
+
+## 🧭 Overview
+This document provides an overview of the different API versions available in the OVHcloud ecosystem and their key features.
+
+### API V6
+Legacy customer-facing REST API. No deprecation plan.
+- RESTful architecture
+
+- OAuth2 authentication
+- Resource management for all OVHcloud products
+
+**Pros:** stable, comprehensive coverage  
+**Cons:** older architecture, slower for high-volume ops
+
+### API V2
+Modernized REST API using OpenAPI 3 and semver.
+- OAuth2 support
+- Common patterns and improved expressiveness
+
+**Pros:** faster, unified schema  
+**Cons:** migration effort, ongoing development
+
+### ICEBERG
+Core backend engine providing sorting, filtering, search, cache management.
+
+**Pros:** provides sorting/filtering out of the box  
+**Cons:** first call heavier due to data load
+
+### 2API
+Legacy NodeJS middleware aggregating API routes for Manager.  
+⚠️ Not recommended for new developments.
+
+### BFF (Backend for Frontend)
+Replacement for 2API, optimizes frontend-backend communication.
+
+**Pros:** reduces API complexity, improves performance  
+**Cons:** migration and learning curve
+
+### 🔗 References
+- [OVHcloud API Docs](https://api.ovh.com/)
+- OVHcloud Manager Docs (internal link: OVH-TOOLS-PAGES-MANAGER)

.ai-doc/10-architecture/app-folder-structure.md

@@ -0,0 +1,30 @@
+---
+title: Application Folder Structure
+last_update: 2025-10-13
+tags: [structure, folder, react, ovhcloud, manager]
+ai: true
+---
+
+# Application Folder Structure
+
+## Overview
+µ‑apps must share a unified folder structure for maintainability.
+
+```
+µ-application-name/
+├── public/translations/
+├── src/
+│   ├── components/
+│   ├── data/
+│   ├── hooks/
+│   ├── pages/
+│   ├── routes/
+│   ├── App.tsx
+│   ├── i18n.ts
+│   ├── index.scss
+│   ├── main.tsx
+│   └── queryClient.ts
+└── index.html
+```
+
+Each section (components, data, hooks, pages, routes) follows strict conventions described in OVHcloud Manager docs.

.ai-doc/10-architecture/common-translations.md

@@ -0,0 +1,30 @@
+---
+title: Common Translations
+last_update: 2025-10-13
+tags: [translations, i18n, ovhcloud, manager]
+ai: true
+---
+
+# Common Translations
+
+## Purpose
+`@ovh-ux/manager-common-translations` maintains reusable i18n strings across µ‑apps.
+
+### Adding New Namespace
+1. Create folder under `public/translations`.
+2. Add `Messages_fr_FR.json`.
+3. Add keys (no app‑specific prefixes).
+
+### Consuming
+```ts
+import { useTranslation } from 'react-i18next';
+import { NAMESPACES } from '@ovh-ux/manager-common-translations';
+
+const { t } = useTranslation(NAMESPACES.example);
+```
+
+### Duplicated Translations CLI
+```bash
+yarn manager-cli duplicated-translations --app web-office
+```
+Warns about existing keys already present in the common package.

.ai-doc/10-architecture/data-fetching.md

@@ -0,0 +1,35 @@
+---
+title: Data Fetching and Updating in Manager
+last_update: 2025-10-13
+tags: [data, fetching, axios, react-query, ovhcloud, manager]
+ai: true
+---
+
+# Data Fetching and Updating in Manager
+
+## Overview
+In Manager, backend interaction happens in two steps:
+1. Create a function using `axios`.
+2. Wrap it in a custom React hook using **Tanstack Query**.
+
+### HTTP Requests with @ovh-ux/manager-core-api
+
+```ts
+import { apiClient, v6, v2, aapi, fetchIcebergV6, fetchIcebergV2 } from '@ovh-ux/manager-core-api';
+v6.get('/me');
+v2.get('/iam/policy');
+aapi.get('/feature/availability');
+```
+
+### Example: IAM Policies
+(omitted for brevity — contains `useQuery`, `useMutation`, and CRUD hooks).
+
+### Polling Example
+Use `refetchInterval` in `useQuery` to auto-refresh async resource creation (e.g., Public Cloud instances).
+
+```ts
+refetchInterval: (instances = []) =>
+  instanceId &&
+  instances.find(({ id }) => id === instanceId)?.status !== 'ACTIVE'
+    ? 5000 : false
+```

.ai-doc/10-architecture/feature-flipping.md

@@ -0,0 +1,38 @@
+---
+title: Feature Flipping
+last_update: 2025-10-13
+tags: [feature, flipping, bff, ovhcloud, manager]
+ai: true
+---
+
+# Feature Flipping
+
+## Purpose
+Enable or disable frontend features **without redeployment**.
+
+### Prerequisites
+- Access to EU/CA/US *feature-availability* BFF repositories
+- Go 1.23+, JFrog CLI, and `xcode-select`
+
+### Definition
+Features live as JSON under `main/`, split by domain (e.g., `sms.json`).  
+Uses **feature-rules** for evaluation based on context and options.
+
+### Usage Examples
+```bash
+GET /feature/sms/availability
+GET /feature/sms,sms:order/availability
+```
+
+### Headers
+| Header | Description |
+|--------|--------------|
+| `X-OVH-FEATURE-SEPARATOR` | custom separator for feature list |
+| `X-OVH-SUBFEATURE-SEPARATOR` | defines subfeature delimiter |
+| `referer` | defines request origin |
+
+### Explain CLI
+```bash
+npm run explain featurename
+npm run explain featurename:subfeature -- --all
+```