khadhroony-bot3/docs/README.md

Documentation active de Khadhroony Bot3

1. Statut

Ce répertoire contient la documentation active, normative ou opérationnelle de khadhroony-bot3.

La documentation historique est conservée sous olddocs/. Les documents archivés ne doivent pas être considérés seuls comme normatifs ; les règles, guides, matrices et rapports finaux actifs décrivent l’état courant.

2. Architecture

• architecture/PROJECT_OBJECTIVES.md : objectifs et limites du projet ;
• architecture/ARCHITECTURE.md : couches et flux principaux ;
• architecture/CRATE_MAP.md : responsabilités des 11 crates ;
• architecture/PIPELINE_ARCHITECTURE.md : orchestration, replay et exécution ;
• architecture/STORAGE_ARCHITECTURE.md : contrats de stockage et PostgreSQL ;
• architecture/SURFACE_CRATE_MATRIX.md : répartition des responsabilités par surface.

3. Règles

Le point d’entrée normatif unique est ../RULES.md.

Règles spécialisées :

• rules/RULES_GENERAL.md ;
• rules/RULES_RUST.md ;
• rules/RULES_SPECIFIC_KHADHROONY.md ;
• rules/CRATE_DOCUMENTATION_RULES.md ;
• rules/VERSION_DEVELOPMENT_LIFECYCLE.md.

Modèles documentaires non génératifs :

• templates/CRATE_README_TEMPLATE.md ;
• templates/CRATE_TODO_TEMPLATE.md ;
• templates/CRATE_USAGE_TEMPLATE.md ;
• templates/CRATE_CHANGELOG_TEMPLATE.md.

4. Audits et décisions actifs

• audits/V0_4_7_PRE_016_DOCUMENTATION_AND_HEADERS_AUDIT.md ;
• decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md ;
• decisions/WINCODE_COMPATIBILITY_POLICY.md.

Les audits et rapports de travail 0.4.8-pre.* sont archivés sous ../olddocs/archivekbot3/. Leur contenu reste disponible pour la traçabilité mais n’est plus un index actif.

5. Documents techniques actifs

• DEVNET_EXECUTION_GUIDE.md ;
• IDL_AUDIT.md ;
• IDL_TO_KB_LIB_NOMENCLATURE.md ;
• MISSING_PROGRAM_IDLS.md ;
• OPERATION_NAMING_CONVENTION.md ;
• IDEA_REMINDERS.md.

Les idées ne rejoignent un TODO.md qu’après confirmation, attribution et reformulation en tâche vérifiable.

6. Matrices contractuelles

Les matrices canoniques sont conservées sous :

test-fixtures/contract-matrices/

Elles peuvent être chargées directement par les tests unitaires ou d’intégration. Elles ne doivent pas être dupliquées sous docs/.

7. Documentation par crate

Les onze crates possèdent README.md, TODO.md, USAGE.md et CHANGELOG.md :

• kb-core ;
• kb-config ;
• kb-lib ;
• kb-logging ;
• kb-program-ids ;
• kb-pipeline ;
• kb-pipeline-demo-scenarios ;
• kb-onchain-transport ;
• kb-store ;
• kb-wallet ;
• kb-app-demo-desktop.

8. Guides

• Configuration ;
• Logging et tracing ;
• RPC, backfill et WebSocket ;
• Extraction Core, replay et matérialisation ;
• PostgreSQL et stockage ;
• Validation Devnet.

9. Rapports de validation actifs

• Validation Metaplex Token Metadata 0.4.7 ;
• Validation Metadata on-chain et clôture 0.4.8 ;
• validation/WEBSOCKET_MAINNET_RESEARCH_VALIDATION_REPORT.md ;
• validation/MAINNET_RESEARCH_BACKFILL_VALIDATION_SCENARIO.md.

Les preuves détaillées de 0.4.8-pre.* restent accessibles sous ../olddocs/archivekbot3/docs/validation/ et dans validation/evidence/v0.4.8/.

10. Plans de version actifs

• Plan 0.5.0 — cadrage de la fondation 0.5.x : plan temporaire actif créé pendant 0.5.0-pre.001, à maintenir jusqu’à la clôture de 0.5.0.
• Audit 0.5.0-pre.002 — configuration, logging, wallet et namespaces : décisions de sécurité, split logging, namespace KS_*, migration wallet et audit du possible préfixe de crates ks-*.

Le plan 0.4.8 reste archivé sous ../olddocs/archivekbot3/docs/plans/.

11. Prompt de reprise

• Prompt actif 0.5.0.