<!-- file: docs/DOCUMENTATION_REFACTOR_PLAN.md -->
<!-- version: 5 -->

# Plan de refonte documentaire

## 1. Objectif

Ce plan transforme progressivement la documentation de `khadhroony-bot3 v0.1.0-pre.062` sans mélanger audit, déplacements, réécriture historique, documentation par crate et décision de réalignement vers `0.4.6`.

Aucune version Cargo ne doit être modifiée avant la conclusion de `docs/V0_4_6_ALIGNMENT_AUDIT.md`.

## 2. Principes d’exécution

- livrer des deltas courts et thématiques ;
- ne pas créer en masse des documents vides ;
- documenter une crate à partir de ses APIs publiques, binaires, tests et configurations réels ;
- ne jamais déplacer ni migrer automatiquement un document depuis `olddocs/archivekbot2/` ;
- créer des documents bot3 nouveaux après lecture, sélection, vérification et adaptation des sources historiques ;
- référencer les matrices canoniques de `test-fixtures/contract-matrices/` sans les dupliquer ;
- ne pas inventer d’API ou de validation ;
- archiver avant de retirer un document ayant une valeur historique ;
- corriger toutes les références avant chaque déplacement ;
- conserver séparément les archives bot2 et bot3 ;
- ne pas rouvrir les audits techniques Solana déjà validés sans écart concret ;
- exécuter uniquement les validations réellement nécessaires au delta.

## 3. Contrat documentaire à inscrire dans les règles

Chaque crate du workspace doit posséder les quatre fichiers suivants :

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

### 3.1 `README.md`

Contenu minimal :

- objectif et périmètre ;
- responsabilités et exclusions ;
- fonctionnalités principales ;
- principales APIs ou façades ;
- relations avec les autres crates ;
- liens vers `USAGE.md`, `TODO.md`, `CHANGELOG.md` et l’architecture pertinente.

Le README ne contient pas le journal détaillé des versions.

### 3.2 `TODO.md`

Sections minimales :

- fonctionnalités manquantes ;
- dette technique ;
- tests manquants ;
- validations Devnet/Mainnet manquantes ;
- documentation manquante ;
- dépendances externes ;
- éléments reportés ;
- hors périmètre.

Les sections sans élément doivent indiquer explicitement qu’aucun élément n’est actuellement recensé, plutôt que rester vides.

### 3.3 `USAGE.md`

Contenu minimal :

- objectif ;
- prérequis ;
- configuration ;
- APIs publiques significatives ;
- description des types importants ;
- erreurs et invariants ;
- exemples réalistes ou compilables ;
- au moins un exemple par API publique significative ;
- limites connues ;
- liens vers tests, fixtures et matrices.

Une API n’est documentée qu’après vérification dans le code et les exports publics.

### 3.4 `CHANGELOG.md`

Le changelog de crate distingue :

- non publié ;
- releases ;
- prereleases ;
- correctifs `fix` ;
- ajouts ;
- modifications ;
- corrections ;
- suppressions ;
- migrations ;
- compatibilité ;
- validations ;
- limitations connues.

Il est mis à jour pour tout changement fonctionnel de la crate. Les changements purement documentaires peuvent être regroupés dans une entrée documentaire explicite.

## 4. Arborescence cible

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

olddocs/
├── archivekbot2/
│   ├── README.md
│   ├── CHANGELOG.md
│   ├── ROADMAP.md
│   ├── RULES.md
│   ├── docs/
│   ├── prompts/
│   └── <anciennes-crates>/...
└── archivekbot3/
```

Le premier déplacement structurel devra inclure un tableau de correspondance ancien chemin vers nouveau chemin dans `docs/README.md` ou dans un rapport de migration dédié.

## 5. Séquence de deltas

### Delta 1 — audit et plan

Fichiers ajoutés :

- `docs/DOCUMENTATION_REFACTOR_AUDIT.md` ;
- `docs/DOCUMENTATION_REFACTOR_PLAN.md`.

Aucun déplacement et aucune réécriture massive.

Validations :

```bash
python3 scripts/audit_rust_workspace_rules.py
```

### Delta 2 — archives et index documentaire

Travail :

1. créer `olddocs/archivekbot2/` ;
2. y reconstruire le miroir documentaire de bot2 en conservant les chemins relatifs : documents racine, `docs/`, `prompts/` et documents des anciennes crates ;
3. inclure les fichiers présentant une fonction documentaire démontrée, conformément à la politique de sélection, sans copier le code, les artefacts de build ou les données privées ;
4. appliquer [`decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md`](decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md) pour distinguer matrices, schémas, exemples et IDL documentaires des fixtures et configurations d’exécution ;
4. créer `olddocs/archivekbot3/` ;
5. créer `docs/README.md` ;
6. créer l’arborescence utile sans fichiers factices ;
7. documenter la provenance, la non-normativité et l’intégrité logique de l’archive bot2.

Aucun document bot3 actif ne doit encore être supprimé.

### Delta 3 — règles documentaires (`v0.1.0-pre.065`)

Travail :

1. corriger `docs/rules/RULES_GENERAL.md` pour imposer les quatre fichiers exacts par crate ;
2. interdire `USAGES.md`, retenir définitivement `USAGE.md` et encadrer l’exception `001.README.md` pour les index lexicaux ;
3. créer `docs/rules/CRATE_DOCUMENTATION_RULES.md` ;
4. définir la frontière entre README, TODO, USAGE, CHANGELOG général et changelogs de crates ;
5. imposer que `USAGE.md` documente uniquement les APIs publiques réellement accessibles ;
6. imposer dans chaque changelog de crate une base `0.1.0` décrivant la migration bot2, la consolidation bot3 et les nouvelles normes ;
7. définir la reprise contrôlée des idées confirmées de `docs/IDEA_REMINDERS.md` dans les TODO ;
8. interdire toute duplication des matrices canoniques de `test-fixtures/contract-matrices/` ;
9. préciser les statuts Metaplex Token Metadata, ElGamal et IDL ;
10. fournir quatre modèles documentaires non génératifs.

Les règles secondaires restent temporairement à la racine dans ce delta.

### Delta 4 — déplacement des règles secondaires

Travail :

1. créer `docs/rules/` ;
2. déplacer `docs/rules/RULES_GENERAL.md`, `docs/rules/RULES_RUST.md` et `docs/rules/RULES_SPECIFIC_KHADHROONY.md` ;
3. mettre à jour `RULES.md` ;
4. corriger les liens internes ;
5. adapter `scripts/audit_khadhroony_workspace_rules.py` ;
6. corriger les références dans prompts, README et documents d’onboarding ;
7. vérifier qu’aucune référence active aux anciens chemins ne subsiste.

Validations obligatoires :

```bash
python3 scripts/audit_rust_workspace_rules.py
```

### Delta 5 — documentation générale bot3 (`v0.1.0-pre.067`)

Travail :

1. remplacer le README racine obsolète par une présentation stable ;
2. créer les objectifs et l’architecture générale ;
3. créer la carte des 11 crates ;
4. documenter les architectures pipeline et stockage ;
5. créer une matrice de responsabilités par surface sans dupliquer les matrices contractuelles ;
6. mettre à jour `docs/README.md`.

Ces documents sont réécrits pour bot3 à partir du workspace actuel et des sources historiques vérifiées.

### Delta 6 — changelog général de transition

Travail :

1. préserver une copie historique du changelog bot2 ;
2. reconstruire le changelog bot3 ;
3. reprendre l’historique fonctionnel pertinent de `0.0.1` à `0.4.6` ;
4. ajouter la transition bot2 vers bot3 ;
5. documenter consolidation, renommages et validations `0.1.0-pre.*` ;
6. conserver les limites, notamment ElGamal non validé Devnet ;
7. distinguer clairement version fonctionnelle et prereleases de migration.

Le changelog ne doit pas affirmer que bot3 est déjà officiellement `0.4.6`.

### Delta 7 — roadmap général

Reconstruire `ROADMAP.md` selon les séries suivantes :

- `0.4.6` : fermeture de l’alignement et écarts résiduels ;
- `0.4.7` : poursuite de Metaplex Token Metadata déjà partiellement migré, puis clôture `0.4.x` ;
- `0.5.x` : configuration, scénarios autonomes, CLI, fixtures et wallet ;
- `0.6.x` : infrastructure Anchor, reste SPL et Metaplex ;
- `0.7.x` : Meteora ;
- `0.8.x` : Raydium ;
- `0.9.x` : Pump ;
- `0.10.x` : Orca ;
- `0.11.x` : Jupiter ;
- `0.12.x` : OKX et autres routers ;
- `0.13.x` : transports temps réel ;
- `0.14.x` : trading, workers et orchestration ;
- `0.15.x+` : extensions futures.

Le roadmap ne contient ni prereleases, ni correctifs `fix`, ni journal détaillé du passé.

### Delta 8 — documentation des crates fondamentales

Ordre proposé :

1. `kb-core` ;
2. `kb-config` ;
3. `kb-logging` ;
4. `kb-program-ids` ;
5. `kb-store`.

Pour chaque crate : auditer les exports publics, tests, erreurs, exemples existants et dépendances avant de rédiger les quatre fichiers.

### Delta 9 — documentation du noyau fonctionnel

Ordre proposé :

1. `kb-lib` ;
2. `kb-pipeline` ;
3. `kb-onchain-transport`.

`kb-lib` devra être traité par sections cohérentes et liens vers les matrices, sans transformer son README en catalogue exhaustif de toutes les fonctions.

### Delta 10 — démonstrations et wallet

Ordre proposé :

1. `kb-pipeline-demo-scenarios` ;
2. `kb-app-demo-desktop` ;
3. `kb-wallet`.

Les TODO doivent expliciter :

- l’autonomie incomplète éventuelle des scénarios ;
- les contraintes de validation Tauri ;
- le statut d’ébauche de `kb-wallet` et son périmètre `0.5.x`.

### Delta 11 — réorganisation des documents actifs

Travail :

- déplacer les guides et rapports Devnet ;
- classer les documents IDL ;
- classer la convention de nommage ;
- ventiler `IDEA_REMINDERS.md` dans les TODO ou décisions ;
- mettre à jour toutes les références ;
- archiver sous `olddocs/archivekbot3/` les audits et plans remplacés qui conservent une valeur historique.

Aucun déplacement ne doit laisser de lien cassé.

### Delta 12 — refonte des prompts

Travail :

1. copier ou référencer les prompts bot2 historiques dans l’archive appropriée sans les rendre normatifs ;
2. créer `prompts/README.md` ;
3. créer un modèle bot3 contenant mission, base validée, périmètre, hors périmètre, règles, architecture, fichiers à lire, tests, critères de clôture, livraison, limites, décisions reportées et état Git ;
4. migrer les informations bot3 utiles ;
5. archiver les deux prompts de migration actuels lorsque leurs informations ont été reprises.

### Delta 13 — audit d’alignement `0.4.6`

Créer :

```text
docs/V0_4_6_ALIGNMENT_AUDIT.md
```

L’audit synthétise, sans réauditer intégralement les protocoles :

- composants migrés ;
- renommages ;
- consolidations ;
- versions Cargo ;
- noms de crates et binaires ;
- exports ;
- tests ;
- validations Devnet ;
- ElGamal ;
- transports ;
- documentation par crate ;
- prompts et archives ;
- `kb-wallet` ;
- futur split de `kb-config` ;
- autonomie de `kb-pipeline-demo-scenarios` ;
- écarts résiduels.

Conclusion obligatoire :

```text
READY_FOR_0_4_6
READY_WITH_DOCUMENTED_EXCEPTIONS
NOT_READY_FOR_0_4_6
```

### Delta 13 — décision de versionnement

Seulement après validation du delta 12 :

- décider du passage officiel à `0.4.6` ;
- modifier les versions Cargo si la conclusion le permet ;
- mettre à jour changelogs, documentation et prompt de session ;
- exécuter les validations workspace imposées pour les modifications de code ou de structure.

## 6. Matrice de validation

### Documentation pure

```bash
python3 scripts/audit_rust_workspace_rules.py
```

Les opérations Git et leurs contrôles sont réalisés séparément par l’opérateur et ne doivent pas être répétés dans les validations demandées à la session.

### Code, scripts d’audit ou structure utilisée par le code

```bash
cargo fmt --all
cargo check --workspace
cargo clippy --all-targets
python3 scripts/audit_rust_workspace_rules.py
```

Ajouter les tests des crates modifiées.

### Frontend desktop

La validation frontend ne doit jamais utiliser `npm --prefix kb-app-demo-desktop run build`.

La validation runtime se fait par :

```bash
cargo tauri dev -c kb-app-demo-desktop/tauri.conf.json
```

## 7. Risques contrôlés

| Risque                                             | Mesure                                                                      |
|----------------------------------------------------|-----------------------------------------------------------------------------|
| perte d’historique bot2                            | miroir documentaire hiérarchique dans `olddocs/archivekbot2/` avant reprise |
| règles introuvables après déplacement              | correction préalable des scripts et références, delta dédié                 |
| documentation d’API inventée                       | lecture des exports et tests avant rédaction                                |
| changelog général trop détaillé                    | déléguer le détail fonctionnel aux changelogs de crates                     |
| roadmap redevenant une checklist                   | interdire prereleases et correctifs dans le roadmap général                 |
| confusion entre migration et version fonctionnelle | section de transition explicite et audit d’alignement séparé                |
| fausse validation ElGamal                          | conserver le statut non validé Devnet                                       |
| modification massive difficile à relire            | un thème documentaire par delta                                             |

## 8. Première décision attendue

Valider le présent audit et le séquençage des deltas avant :

- la copie de l’archive bot2 dans `olddocs/` ;
- le déplacement des règles ;
- la reconstruction du changelog et du roadmap ;
- la création des documents par crate ;
- la modification des versions Cargo.