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

# Documentation active de Khadhroony Bot3

## 1. Statut

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

La documentation historique de `khadhroony-bot2` est conservée sous `olddocs/archivekbot2/`. Elle ne doit être ni déplacée vers `docs/`, ni considérée comme normative. Tout nouveau document bot3 est réécrit après lecture du code, des tests, des matrices et des sources historiques pertinentes.

## 2. Architecture

- [`architecture/PROJECT_OBJECTIVES.md`](architecture/PROJECT_OBJECTIVES.md) : objectifs et limites du projet ;
- [`architecture/ARCHITECTURE.md`](architecture/ARCHITECTURE.md) : couches et flux principaux ;
- [`architecture/CRATE_MAP.md`](architecture/CRATE_MAP.md) : responsabilités des 11 crates ;
- [`architecture/PIPELINE_ARCHITECTURE.md`](architecture/PIPELINE_ARCHITECTURE.md) : orchestration, replay et exécution ;
- [`architecture/STORAGE_ARCHITECTURE.md`](architecture/STORAGE_ARCHITECTURE.md) : contrats de stockage et PostgreSQL ;
- [`architecture/SURFACE_CRATE_MATRIX.md`](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`](../RULES.md).

Règles spécialisées :

- [`rules/RULES_GENERAL.md`](rules/RULES_GENERAL.md) ;
- [`rules/RULES_RUST.md`](rules/RULES_RUST.md) ;
- [`rules/RULES_SPECIFIC_KHADHROONY.md`](rules/RULES_SPECIFIC_KHADHROONY.md) ;
- [`rules/CRATE_DOCUMENTATION_RULES.md`](rules/CRATE_DOCUMENTATION_RULES.md).

Modèles documentaires non génératifs :

- [`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).

## 4. Audits et décisions actifs

- [`audits/V0_4_7_PRE_016_DOCUMENTATION_AND_HEADERS_AUDIT.md`](audits/V0_4_7_PRE_016_DOCUMENTATION_AND_HEADERS_AUDIT.md) ;
- [`audits/V0_4_8_PRE_002_METADATA_CONTRACT_AUDIT.md`](audits/V0_4_8_PRE_002_METADATA_CONTRACT_AUDIT.md) ;
- [`decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md`](decisions/DOCUMENT_ARCHIVE_SELECTION_POLICY.md) ;
- [`decisions/WINCODE_COMPATIBILITY_POLICY.md`](decisions/WINCODE_COMPATIBILITY_POLICY.md).

Ces audits seront archivés sous `olddocs/archivekbot3/` lorsqu’ils auront été remplacés par des documents normatifs ou des rapports de clôture.

## 5. Documents techniques actifs

- [`DEVNET_EXECUTION_GUIDE.md`](DEVNET_EXECUTION_GUIDE.md) ;
- [`IDL_AUDIT.md`](IDL_AUDIT.md) ;
- [`IDL_TO_KB_LIB_NOMENCLATURE.md`](IDL_TO_KB_LIB_NOMENCLATURE.md) ;
- [`MISSING_PROGRAM_IDLS.md`](MISSING_PROGRAM_IDLS.md) ;
- [`OPERATION_NAMING_CONVENTION.md`](OPERATION_NAMING_CONVENTION.md) ;
- [`IDEA_REMINDERS.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 :

```text
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/`. Les documents actifs peuvent les référencer et expliquer leur rôle.

## 7. Documentation par crate

Les onze crates possèdent désormais `README.md`, `TODO.md`, `USAGE.md` et `CHANGELOG.md` :

- [`kb-core`](../kb-core/README.md) ;
- [`kb-config`](../kb-config/README.md) ;
- [`kb-lib`](../kb-lib/README.md) ;
- [`kb-logging`](../kb-logging/README.md) ;
- [`kb-program-ids`](../kb-program-ids/README.md) ;
- [`kb-pipeline`](../kb-pipeline/README.md) ;
- [`kb-pipeline-demo-scenarios`](../kb-pipeline-demo-scenarios/README.md) ;
- [`kb-onchain-transport`](../kb-onchain-transport/README.md) ;
- [`kb-store`](../kb-store/README.md) ;
- [`kb-wallet`](../kb-wallet/README.md) ;
- [`kb-app-demo-desktop`](../kb-app-demo-desktop/README.md).

## Guides

- [Configuration](guides/CONFIGURATION.md)
- [Logging et tracing](guides/LOGGING.md)
- [RPC, backfill et WebSocket](guides/RPC_BACKFILL_AND_WEBSOCKET.md)
- [Extraction Core, replay et matérialisation](guides/REPLAY_CORE_EXTRACTION_AND_MATERIALIZATION.md)
- [PostgreSQL et stockage](guides/POSTGRES_STORAGE.md)
- [Validation Devnet](guides/DEVNET_VALIDATION.md)
- [Validation Metaplex Token Metadata 0.4.7](validation/V0_4_7_METAPLEX_TOKEN_METADATA_VALIDATION_REPORT.md)
- [`validation/WEBSOCKET_MAINNET_RESEARCH_VALIDATION_REPORT.md`](validation/WEBSOCKET_MAINNET_RESEARCH_VALIDATION_REPORT.md) ;
- [`validation/MAINNET_RESEARCH_BACKFILL_VALIDATION_SCENARIO.md`](validation/MAINNET_RESEARCH_BACKFILL_VALIDATION_SCENARIO.md) ;

## Audits actifs

- [`Audit contractuel 0.4.8-pre.002 — metadata`](audits/V0_4_8_PRE_002_METADATA_CONTRACT_AUDIT.md) ;
- [`Audit 0.4.8-pre.005 — instructions et historique Solana Program Metadata`](audits/V0_4_8_PRE_005_SOLANA_PROGRAM_METADATA_INSTRUCTION_HISTORY_AUDIT.md).

## Plans de version actifs

- [`Plan 0.4.8 — Solana Program Metadata et complétude Token-2022`](plans/V0_4_8_SOLANA_PROGRAM_METADATA_AND_TOKEN_2022_COMPLETENESS_PLAN.md).

## Prompt de reprise

- [`Prompt actif 0.4.8`](../prompts/028_v0_4_8_spl_token_metadata_and_offchain_decision.md).