spec OKF pour doc

AGENTS.md

@@ -43,3 +43,10 @@ WGPU doesn't have a native "Context" object — this type groups them together f
 - wgpu 30.0.0 is pinned in `lib/Cargo.toml`. The comment says "check the latest version" — verify compatibility before upgrading.
 - No feature flags, no dev-dependencies, no tests yet. Adding any requires updating both `Cargo.toml` files if the dependency spans crates.
 - The workspace has no `[workspace.dependencies]` section. Dependencies are declared per-crate rather than centrally.
+
+<!-- lean-ctx -->
+## lean-ctx
+
+Prefer lean-ctx MCP tools over native equivalents for token savings.
+Full rules: @LEAN-CTX.md
+<!-- /lean-ctx -->

AGENTS.md.bak

@@ -0,0 +1,45 @@
+# WSG - WGPU Simple Graphics Library
+
+## Project Type
+Rust workspace (2024 edition) wrapping [wgpu](https://github.com/gfx-rs/wgpu) for simple 3D drawing operations.
+
+## Workspace Structure
+```
+Cargo.toml          # workspace root — no dependencies here
+lib/Cargo.toml      # wsg-lib crate: wgpu 30.0.0, winit 0.30
+examples/Cargo.toml # depends on wsg-lib via path reference
+lib/lib.rs          # lib entry point
+lib/context.rs      # Context type (aggregates wgpu objects: Instance, Surface, Adapter, Device, Queue)
+lib/renderer.rs     # renderer implementation
+examples/src/main.rs # example binary
+```
+
+**Key convention**: `wsg-lib` is referenced from `examples/` via relative path (`path = "../lib"`). Do not publish this to crates.io as-is — it uses a local path dependency.
+
+## Essential Commands
+| Action | Command |
+|--------|---------|
+| Build everything | `cargo build --workspace` |
+| Run examples | `cargo run -p examples` |
+| Test | `cargo test --workspace` |
+| Check | `cargo check --workspace` |
+| Format | `cargo fmt --all` |
+
+No custom scripts or linting tooling beyond standard Cargo conventions.
+
+## Architecture Overview
+The library's purpose is to abstract the five core wgpu objects into a single **Context**:
+
+- **Instance** — GPU backend selection (Vulkan/Metal/DX12)
+- **Surface** — window rendering surface (via winit)
+- **Adapter** — physical/logical GPU device
+- **Device** — buffer/texture/pipeline creation
+- **Queue** — command submission
+
+WGPU doesn't have a native "Context" object — this type groups them together for a simpler user API. See README.md for the French documentation of each component.
+
+## Gotchas
+- Rust 2024 edition is used. Ensure your Rust toolchain supports it (`rustup update`).
+- wgpu 30.0.0 is pinned in `lib/Cargo.toml`. The comment says "check the latest version" — verify compatibility before upgrading.
+- No feature flags, no dev-dependencies, no tests yet. Adding any requires updating both `Cargo.toml` files if the dependency spans crates.
+- The workspace has no `[workspace.dependencies]` section. Dependencies are declared per-crate rather than centrally.

LEAN-CTX.md

@@ -0,0 +1,50 @@
+<!-- lean-ctx-owned: PROJECT-LEAN-CTX.md v1 -->
+# lean-ctx — Context Engineering Layer
+<!-- lean-ctx-rules-v11 -->
+
+## Tool Mapping (MANDATORY — use instead of native equivalents)
+| Instead of | Use | Example |
+|------------|-----|---------|
+| Read/cat/head/tail | `ctx_read(path, mode)` | `ctx_read("src/main.rs", "full")` |
+| Grep/rg/find | `ctx_search(pattern, path)` | `ctx_search("fn handle", "src/")` |
+| Shell/bash | `ctx_shell(command)` | `ctx_shell("cargo test")` |
+| Edit (when Read unavailable) | `ctx_edit(path, old, new)` | `ctx_edit("f.rs", "old", "new")` |
+
+## ctx_read Mode Selection
+| Goal | Mode | When |
+|------|------|------|
+| Edit this file | `full` | Before any edit |
+| Understand API | `signatures` | Context-only, won't edit |
+| Re-read after edit | `diff` | Post-edit verification |
+| Large file overview | `map` | >500 lines, won't edit |
+| Specific region | `lines:N-M` | Know exact location |
+| Unsure | `auto` | System selects optimal mode |
+
+## Workflow (follow this order)
+1. **Orient:** `ctx_overview(task)` or `ctx_compose(task, path)` for unfamiliar tasks
+2. **Locate:** `ctx_search(pattern, path)` for exact text; `ctx_semantic_search(query)` for concepts
+3. **Read:** `ctx_read(path, mode)` with appropriate mode from table above
+4. **Edit:** `ctx_edit(path, old_string, new_string)` or native Edit if available
+5. **Verify:** `ctx_read(path, "diff")` + `ctx_shell("test command")`
+6. **Record:** `ctx_knowledge(action="remember", content="...")` for non-obvious findings
+
+## Proactive (use without being asked)
+- `ctx_overview(task)` — at session start for orientation
+- `ctx_compress` — when context grows large (at phase boundaries)
+- `ctx_knowledge(action="wakeup")` — at session start to surface prior findings
+
+## Compression Bypass (only when compressed output hides needed detail)
+`ctx_read(path, "lines:N-M")` → `ctx_read(path, "full")` → `ctx_shell(cmd, raw=true)`
+Return to compressed defaults after one expanded retrieval.
+
+## Risk Gate (before high-impact edits)
+Before editing exported symbols, auth, DB schemas, or 3+ files: run `ctx_impact(action="analyze")`
+and `ctx_callgraph(action="callers")` to confirm blast radius.
+
+## Session
+- **Start:** `ctx_session(action="status")` + `ctx_knowledge(action="wakeup")`
+- **End:** `ctx_session(action="decision", content="what was done + next steps")`
+- **On [CHECKPOINT]:** `ctx_session(action="task", value="current status")`
+
+NEVER use native Read/Grep/Shell when ctx_* equivalents are available.
+<!-- /lean-ctx -->

README.md

@@ -2,6 +2,9 @@
 
 WSG is a Rust library that wraps [wgpu](https://github.com/gfx-rs/wgpu) to provide a simple, declarative API for 3D graphics. It abstracts away the complexity of managing GPU resources while exposing low-level primitives for advanced users.
 
+
+NOTE : the development version is currently unstable and the examples described below may not work as expected.
+
 ## What it does
 
 WSG provides two complementary workflows:

docs/PLAN.md

@@ -1,6 +1,15 @@
+---
+type: Plan
+title: Implementation Plan for wsg_lib Engine Consolidation and Finalization
+description: Implementation plan defining priority steps to finalize the current architecture, making the API intuitive for standard users while maintaining power for advanced users
+tags: [plan, implementation, roadmap, development, wsg-lib]
+status: stable
+generated: { by: human:jerome, at: 2026-07-31T00:00:00Z }
+---
+
 # Plan d'Implémentation : Consolidation et Finalisation du Moteur wsg_lib
 
-Ce plan définit les étapes prioritaires pour stabiliser l'architecture actuelle. L'objectif est de rendre l'API intuitive pour l'utilisateur standard tout en conservant la puissance de contrôle pour l'utilisateur avancé.
+Ce plan définit les étapes prioritaires pour finaliser l'architecture actuelle. L'objectif est de rendre l'API intuitive pour l'utilisateur standard tout en conservant la puissance de contrôle pour l'utilisateur avancé.
 
 ## Phase 1 : Finalisation et Nettoyage de l'Existant (Priorité Absolue)
 
@@ -8,20 +17,20 @@ Cette phase vise à supprimer la dette technique et à unifier les accès.
 
 ### Uniformisation des Modules
 
-- Vérifier que tous les traits (`AppHandler`) et structures (`App`, `Context`) sont explicitement marqués `pub` dans leurs fichiers sources.
-- Ré-exporter l'API dans `lib.rs` pour permettre des imports simplifiés (ex : `use wsg_lib::{App, AppHandler}`).
-- Nettoyer les accès internes pour que l'utilisateur n'ait pas à importer les modules système (`core`, `pipeline`) sauf besoin spécifique.
+- [X] Vérifier que tous les traits (`AppHandler`) et structures (`App`, `Context`) sont explicitement marqués `pub` dans leurs fichiers sources.
+- [X] Ré-exporter l'API dans `lib.rs` pour permettre des imports simplifiés (ex : `use wsg_lib::{App, AppHandler}`).
+- [X] Nettoyer les accès internes pour que l'utilisateur n'ait pas à importer les modules système (`core`, `pipeline`) sauf besoin spécifique.
 
 ### Abstraction de la Boucle (`App::run`)
 
-- Déplacer la gestion de `winit::event_loop` et des `Frame` à l'intérieur de la méthode `run()` de `App`.
-- Garantir que le trait `AppHandler` reçoit une référence à `App` permettant d'appeler `app.renderer` ou `app.scene`.
-- Supprimer toute gestion de `Frame` ou `EventLoop` manuelle des exemples utilisateurs (`simple.rs`).
+- [X] Déplacer la gestion de `winit::event_loop` et des `Frame` à l'intérieur de la méthode `run()` de `App`.
+- [X] Garantir que le trait `AppHandler` reçoit une référence à `App` permettant d'appeler `app.renderer` ou `app.scene`.
+- [X] Supprimer toute gestion de `Frame` ou `EventLoop` manuelle des exemples utilisateurs (`simple.rs`).
 
 ### Correction du Builder et Initialisation
 
-- Standardiser la création de `App` via un `AppBuilder` robuste.
-- Gérer les `dev-dependencies` dans `lib/Cargo.toml` (notamment `pollster` avec la feature `macro`) pour permettre la compilation des exemples sans polluer les dépendances finales de la librairie.
+- [X] Standardiser la création de `App` via un `AppBuilder` robuste.
+- [X] Gérer les `dev-dependencies` dans `lib/Cargo.toml` (notamment `pollster` avec la feature `macro`) pour permettre la compilation des exemples sans polluer les dépendances finales de la librairie.
 
 ## Phase 2 : Structure de Rendu et Scène
 
@@ -29,39 +38,39 @@ Une fois la plomberie encapsulée, nous devons rendre l'assemblage des objets co
 
 ### Intégration de la Scene
 
-- Formaliser la structure `Scene` : un conteneur qui liste les Entities.
-- Associer le `PipelineCache` à la Scene pour que le rendu des matériaux soit automatique.
-- Implémenter la logique `app.render(scene)` : cette méthode doit parcourir la scène, récupérer les matériaux, gérer les pipelines via le cache, et soumettre les draw calls.
+- [X] Formaliser la structure `Scene` : un conteneur qui liste les Entities.
+- [X] Associer le `PipelineCache` à la Scene pour que le rendu des matériaux soit automatique.
+- [X] Implémenter la logique `app.render(scene)` : cette méthode doit parcourir la scène, récupérer les matériaux, gérer les pipelines via le cache, et soumettre les draw calls.
 
 ### Gestion des Matériaux et Shaders
 
-- S'assurer que chaque Mesh possède une référence vers un Material.
-- Implémenter le comportement par défaut : si aucun matériau n'est assigné, le moteur injecte automatiquement le `basic_shader`.
+- [X] S'assurer que chaque Mesh possède une référence vers un Material.
+- [X] Implémenter le comportement par défaut : si aucun matériau n'est assigné, le moteur injecte automatiquement le `basic_shader`.
 
 ## Phase 3 : Documentation et Interface (API "User-Friendly")
 
 ### Refonte des Exemples
 
-- `simple.rs` doit devenir le modèle : **15 lignes** de code, pas de manipulation WGPU explicite.
-- `manual.rs` doit rester disponible en tant que tutoriel pour ceux qui veulent contourner l'abstraction App.
+- [X] `simple.rs` doit devenir le modèle : **15 lignes** de code, pas de manipulation WGPU explicite.
+- [X] `manual.rs` doit rester disponible en tant que tutoriel pour ceux qui veulent contourner l'abstraction App.
 
 ### Nettoyage du Code Interne
 
-- Vérifier les durées de vie (lifetimes) et les Arc pour s'assurer qu'aucune fuite mémoire ou accès concurrentiel invalide ne survient lors des changements de frame.
+- [X] Vérifier les durées de vie (lifetimes) et les Arc pour s'assurer qu'aucune fuite mémoire ou accès concurrentiel invalide ne survient lors des changements de frame.
 
 ## Phase 4 : Nouvelles Fonctionnalités (Planification Future)
 
 Une fois les phases 1 à 3 validées, nous pourrons introduire :
 
-- **Système de Lumières** : Ajout de buffers d'uniformes dans le PipelineCache.
-- **Textures** : Intégration d'un module de chargement d'images et de BindGroups.
-- **Caméras** : Gestion des matrices de projection/vue dans la Scene.
+- [ ] **Système de Lumières** : Ajout de buffers d'uniformes dans le PipelineCache.
+- [ ] **Textures** : Intégration d'un module de chargement d'images et de BindGroups.
+- [ ] **Caméras** : Gestion des matrices de projection/vue dans la Scene.
 
 ## Check-list de Vérification pour le LLM d'Assistance
 
-- [ ] Est-ce que `simple.rs` compile sans importer `winit` ou `wgpu` ?
-- [ ] Est-ce que `App::run` gère bien le cycle update → render → present ?
-- [ ] Les modules sont-ils bien exposés via `lib.rs` ?
-- [ ] `pollster` est-il uniquement en dev-dependencies ?
+- [X] Est-ce que `simple.rs` compile sans importer `winit` ou `wgpu` ?
+- [X] Est-ce que `App::run` gère bien le cycle update → render → present ?
+- [X] Les modules sont-ils bien exposés via `lib.rs` ?
+- [X] `pollster` est-il uniquement en dev-dependencies ?
 
 Ce plan garantit que les fondations sont saines. Une fois la Scene rendue automatiquement par `app.render()`, l'ajout de toute nouvelle fonctionnalité (lumières, textures) deviendra une simple question d'ajout de données dans la structure de scène, sans modification de la boucle de rendu.

docs/ROADMAP.md

@@ -1,3 +1,12 @@
+---
+type: Roadmap
+title: WSG Engine Development Roadmap
+description: Development roadmap for the WSG engine from prototype to full-featured 3D rendering engine
+tags: [roadmap, development, planning, wsg-lib, 3d-rendering]
+status: stable
+generated: { by: human:jerome, at: 2026-07-31T00:00:00Z }
+---
+
 # Roadmap WSG — Prototype → Moteur Complet
 
 > Basé sur l'architecture existante (ARCHI_APP, ARCHI_ARENES, ARCHI_CPU_GPU, ARCHI_RENDU).

docs/rules/DOCUMENTATION.md

@@ -1,4 +1,13 @@
-# IAgent Documentation
+---
+type: Reference
+title: IAgent Documentation Rules
+description: Rules and guidelines for documentation in the IAgent project, following OKF v0.2 specification
+tags: [documentation, guidelines, standards]
+status: stable
+generated: { by: human:jerome, at: 2026-07-31T00:00:00Z }
+---
+
+# IAgent Documentation Rules
 
 ## Language
 

docs/tech/ARCHI_APP.md

@@ -1,3 +1,12 @@
+---
+type: Architecture
+title: wsg_lib Engine Architecture
+description: Technical architecture and design principles of the wsg_lib rendering engine
+tags: [architecture, rendering, graphics, wgpu, engine]
+status: stable
+generated: { by: human:jerome, at: 2026-07-31T00:00:00Z }
+---
+
 # Architecture du Moteur wsg_lib
 
 wsg_lib est un moteur de rendu modulaire basé sur wgpu. Il adopte une architecture à deux niveaux : une façade de haut niveau pour la productivité et un accès bas niveau pour un contrôle total.

docs/tech/ARCHI_ARENES.md

@@ -1,3 +1,12 @@
+---
+type: Technical Specification
+title: Generational Arena Resource Management with slotmap
+description: Technical specification for efficient and safe resource management using generational arenas implemented via the slotmap crate
+tags: [architecture, resources, performance, safety, slotmap, arena]
+status: stable
+generated: { by: human:jerome, at: 2026-07-31T00:00:00Z }
+---
+
 # Fiche Technique : Gestion des Ressources avec des Arènes Générationalles (`slotmap`)
 
 Cette fiche technique détaille l'implémentation recommandée pour gérer efficacement et en toute sécurité les ressources (maillages, textures, matériaux, lumières, etc.) au sein du moteur graphique WSG. Nous utilisons le concept d'**arène générationalle**, implémenté via la crate `slotmap`, pour bénéficier d'IDs stables, de performances optimales, de sécurité accrue et de fonctionnalités avancées comme les `SecondaryMap`.

docs/tech/ARCHI_CPU_GPU.md

@@ -1,3 +1,12 @@
+---
+type: Technical Specification
+title: GPU-Driven 3D Rendering Architecture with wGPU
+description: Technical specification for GPU-driven 3D rendering architecture using wgpu, focusing on CPU-GPU workload distribution and performance optimization
+tags: [architecture, rendering, gpu, cpu, performance, wgpu]
+status: stable
+generated: { by: human:jerome, at: 2026-07-31T00:00:00Z }
+---
+
 Architecture de Rendu 3D GPU-Driven avec wGPU : 
 Bonnes Pratiques & Guide d'Implémentation
 

docs/tech/ARCHI_RENDU.md

@@ -1,3 +1,12 @@
+---
+type: Technical Specification
+title: Rendering Architecture: Update/Render Cycle and Data Management
+description: Technical specification for the rendering architecture of wsg_lib, defining strategies for mutability and data management to maximize performance and memory safety in Rust
+tags: [architecture, rendering, rust, performance, memory-safety]
+status: stable
+generated: { by: human:jerome, at: 2026-07-31T00:00:00Z }
+---
+
 # Architecture de Rendu : Cycle Update/Render et Gestion des Données
 
 Ce document définit la stratégie de gestion de la mutabilité et des données du moteur wsg_lib, conçue pour maximiser la performance et garantir la sécurité mémoire via Rust.

docs/tech/FRAME_LOOP.md

@@ -1,3 +1,12 @@
+---
+type: Technical Specification
+title: Frame Loop Architecture
+description: Technical specification for the frame loop architecture in wsg_lib, detailing the immutable frame lifetime cycle and resource management
+tags: [architecture, rendering, frame-loop, gpu, wgpu]
+status: stable
+generated: { by: human:jerome, at: 2026-07-31T00:00:00Z }
+---
+
 # La Boucle de Rendu (Frame Loop)
 
 Pour afficher quelque chose, nous suivons un cycle immuable appelé la Frame Lifetime. Dans ton `main.rs` (l'orchestrateur), le flux est désormais le suivant :