khadhroony-bot3/docs/DOCUMENTATION_REFACTOR_PLAN.md

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 :

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

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 :

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 pour distinguer matrices, schémas, exemples et IDL documentaires des fixtures et configurations d’exécution ;
5. créer olddocs/archivekbot3/ ;
6. créer docs/README.md ;
7. créer l’arborescence utile sans fichiers factices ;
8. 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 RULES_GENERAL.md pour imposer les quatre fichiers exacts par crate ;
2. supprimer les variantes obsolètes 001.README.md et USAGES.md, et retenir définitivement USAGE.md ;
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 RULES_GENERAL.md, RULES_RUST.md et 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 :

python3 scripts/audit_rust_workspace_rules.py

Delta 5 — 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 6 — 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 7 — 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 8 — 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 9 — 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 10 — 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 11 — 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 12 — audit d’alignement 0.4.6

Créer :

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 :

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

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

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 :

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.