<!-- file: docs/README.md -->
<!-- version: 1 -->

# Documentation de `khadhroony-bot3`

## 1. Rôle

Ce répertoire contient la documentation active, normative ou encore utilisée de `khadhroony-bot3`.

La documentation historique de `khadhroony-bot2` et les documents bot3 remplacés sont conservés séparément sous `olddocs/`. Un document archivé peut servir de source historique, mais il n’est pas normatif pour l’architecture bot3 actuelle.

## 2. Documents de pilotage actifs

| Document                                                                                           | Rôle                                                                              |
|----------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------|
| [`DOCUMENTATION_REFACTOR_AUDIT.md`](DOCUMENTATION_REFACTOR_AUDIT.md)                               | inventaire et écarts documentaires de la base `v0.1.0-pre.062`                    |
| [`DOCUMENTATION_REFACTOR_PLAN.md`](DOCUMENTATION_REFACTOR_PLAN.md)                                 | séquence contrôlée de reconstruction documentaire et d’alignement `0.4.6`         |
| [`decisions/WINCODE_COMPATIBILITY_POLICY.md`](decisions/WINCODE_COMPATIBILITY_POLICY.md)           | justification durable de la contrainte `wincode 0.5.x` et du contrôle du lockfile |
| [`decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md`](decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md) | critères normatifs de conservation et d’exclusion dans les archives documentaires |

## 3. Documents existants à reclasser

Les documents suivants restent temporairement à leur chemin actuel jusqu’au delta de réorganisation :

- `DEVNET_EXECUTION_GUIDE.md` ;
- `PRE_062_DEVNET_VALIDATION_REPORT.md` ;
- `OPERATION_NAMING_CONVENTION.md` ;
- `IDL_AUDIT.md` ;
- `IDL_TO_KB_LIB_NOMENCLATURE.md` ;
- `MISSING_PROGRAM_IDLS.md` ;
- `IDEA_REMINDERS.md`.

Leur présence à la racine de `docs/` est transitoire. Ils ne doivent pas être déplacés avant correction de leurs références.

## 4. Arborescence cible

```text
docs/
├── README.md
├── architecture/
├── audits/
├── decisions/
├── generated/
├── guides/
├── migrations/
├── protocols/
├── rules/
└── validation/
```

Les répertoires sont créés lorsqu’un document réel doit y être classé. Aucun fichier factice n’est requis.

## 5. Archives historiques

### 5.1 Archive bot2

```text
olddocs/archivekbot2/
```

Cette archive reproduit les chemins relatifs des fichiers sélectionnés selon leur fonction documentaire dans l’archive complète bot2 fournie pour la session. La sélection ne dépend pas de l’extension et suit [`decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md`](decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md). Elle comprend notamment :

- les documents racine historiques ;
- `docs/` ;
- `prompts/` ;
- les README, changelogs et autres documents des anciennes crates ;
- les matrices, schémas, exemples de configuration et IDL ayant une valeur documentaire démontrée.

Les fichiers sont conservés sans adaptation de fond. Les liens relatifs peuvent viser l’ancienne arborescence bot2 et ne garantissent pas une navigation fonctionnelle depuis bot3.

### 5.2 Archive bot3

```text
olddocs/archivekbot3/
```

Cette archive recevra progressivement les audits, plans, prompts et documents bot3 remplacés qui conservent une valeur historique, décisionnelle ou de traçabilité.

## 6. Contrat documentaire des crates

Chaque crate doit finalement posséder exactement :

```text
README.md
TODO.md
USAGE.md
CHANGELOG.md
```

`USAGE.md` est la convention retenue. La variante `USAGES.md` est obsolète.

Le contenu attendu de chaque fichier est défini par [`rules/CRATE_DOCUMENTATION_RULES.md`](rules/CRATE_DOCUMENTATION_RULES.md). Les modèles de `docs/templates/` servent uniquement d’aide à la rédaction.

## 7. Règles de consultation

Ordre recommandé :

1. `RULES.md` à la racine du workspace ;
2. les règles secondaires à leur emplacement normatif courant ;
3. le présent index ;
4. les documents d’architecture ou de validation liés à la tâche ;
5. `olddocs/` uniquement pour l’historique ou la reprise contrôlée d’informations.

## Règles et modèles documentaires

- [`rules/CRATE_DOCUMENTATION_RULES.md`](rules/CRATE_DOCUMENTATION_RULES.md) : contrat normatif des quatre documents de chaque crate ;
- [`templates/CRATE_README_TEMPLATE.md`](templates/CRATE_README_TEMPLATE.md) ;
- [`templates/CRATE_TODO_TEMPLATE.md`](templates/CRATE_TODO_TEMPLATE.md) ;
- [`templates/CRATE_USAGE_TEMPLATE.md`](templates/CRATE_USAGE_TEMPLATE.md) ;
- [`templates/CRATE_CHANGELOG_TEMPLATE.md`](templates/CRATE_CHANGELOG_TEMPLATE.md).

Les modèles ne doivent jamais être remplis mécaniquement : la rédaction exige la lecture du code, des exports publics, des tests et des sources historiques pertinentes.