Clarifier les guides de configuration

Author: raidos23

docs/ark_main_config.md

@@ -1,8 +1,8 @@
-## **ark.yml** — Workspace Configuration
+## **ark.yml** - Workspace Configuration
 
-This file defines the project settings used to build the normalized **BuildContext**. It lives at the workspace root and is created automatically when the workspace is first set in the GUI (if missing).
+This file defines the project settings used to build the normalized **BuildContext**. It lives at the workspace root and is created automatically when the workspace is first configured in the GUI, if missing.
 
-The configuration is loaded by `Core/Configs/` and serves as the primary source of truth for project metadata.
+The configuration is loaded by `Core/Configs/` and is the primary source of truth for project metadata.
 
 ## Minimal Example
 
@@ -37,8 +37,8 @@ plugins:
 
 Behavior:
 
-- When a build is triggered (CLI or GUI), this entrypoint is used to populate the `BuildContext`.
-- In the GUI, you can select any file to compile, but the `project.entry` remains the default configuration.
+- When a build is triggered from the CLI or GUI, this entrypoint is used to populate the `BuildContext`.
+- In the GUI, you can select any file to compile, but `project.entry` remains the default configuration.
 - If it is missing or invalid, compilation is blocked until a valid entrypoint is selected.
 
 GUI shortcuts:
@@ -60,7 +60,7 @@ The fields in `ark.yml` are mapped directly to the `BuildContext` data structure
 | `build.data` | `data_mappings` |
 | `build.icon` | `icon` |
 
-> **Note**: `workspace.exclude` is exclusive to the GUI workspace view filtering (file explorer). `build.exclude` is what determines which files are ignored during the actual compilation (engine) and BCASL phases.
+> **Note**: `workspace.exclude` is used only for the GUI workspace view filter. `build.exclude` determines which files are ignored during compilation and BCASL phases.
 
 ## Plugins Configuration
 
@@ -71,7 +71,7 @@ plugins:
   bcasl_enabled: true  # Global toggle for the BCASL pipeline
 ```
 
-If `bcasl_enabled` is set to `false`, the entire pipeline is skipped during compilation. This setting is also manageable via the **BCASL Pipeline** dialog in the GUI.
+If `bcasl_enabled` is set to `false`, the entire pipeline is skipped during compilation. You can also change this setting in the **BCASL Pipeline** dialog in the GUI.
 
 ## Advanced Config Editor (GUI)
 

docs/how_to_create_a_bc_plugin.md

@@ -1,18 +1,18 @@
-## **BC Plugin Guide**
+## **BCASL Plugin Guide**
 
-## **BCASL = Before Compilation Action System & Loader.**
+**BCASL = Before-Compilation Action System & Loader.**
 
 **Overview**
-A BC plugin (BCASL) is a package placed in `Plugins/` and executed before compilation. It registers automatically, respects execution order (priority, tags, dependencies), and uses `PreCompileContext` to work with the workspace.
+A BC plugin is a package placed in `Plugins/` and executed before compilation. It registers automatically, respects execution order (priority, tags, dependencies), and uses `PreCompileContext` to work with the workspace.
 
-The BCASL engine and loader are **pure-Python** modules, meaning they can run in headless environments (CLI, CI) without any Qt dependencies. UI integration is provided separately by the ARK GUI.
+The BCASL loader and runtime are **pure-Python**. They run in headless environments (CLI, CI) without Qt dependencies. UI integration is provided separately by the ARK GUI.
 
 **Discovery And Loading**
 
 - Plugins are discovered in `Plugins/<plugin_name>/`.
 - The folder must contain an `__init__.py`.
 - The loader imports each package and detects plugins via `@bc_register` or `bcasl_register(manager)`.
-- If `bcasl.yml` is missing, a default file is generated.
+- If `bcasl.yml` is missing, BCASL generates a best-effort default file when it runs.
 
 **Package Layout**
 
@@ -53,8 +53,8 @@ class ExampleClean(BcPluginBase):
         super().__init__(META)
 
     def on_pre_compile(self, ctx: PreCompileContext) -> None:
-        # ctx.root est un objet Path pointant vers la racine du workspace
-        # iter_files() utilise par défaut les patterns d'inclusion/exclusion du projet
+        # ctx.root is a Path to the workspace root.
+        # iter_files() uses the configured include/exclude patterns by default.
         for pyc in ctx.iter_files(["**/*.pyc"]):
             try:
                 pyc.unlink()
@@ -81,7 +81,7 @@ def bcasl_register(manager: BCASL) -> None:
 **PluginMeta And Compatibility**
 Important fields.
 
-- `id`: unique and stable id (used in `bcasl.yml`).
+- `id`: unique, stable id used in `bcasl.yml`.
 - `name`, `version`, `description`, `author`.
 - `tags`: used for default ordering when no explicit order is provided.
 - `required_*_version`: compatibility requirements (BCASL, Core, SDK, Context).
@@ -99,8 +99,8 @@ Validation.
 
 **Configuration (bcasl.yml)**
 For plugin authors, `bcasl.yml` is the canonical workspace config file.
-`PreCompileContext` helpers and validity checks rely on it directly, so it is
-the format you should target in examples and real plugin code.
+`PreCompileContext` helpers and validation logic read it directly, so target
+this format in examples and plugin code.
 
 Example.
 
@@ -131,40 +131,40 @@ Important notes.
 - Global BCASL activation is managed by **`ark.yml`** (`plugins.bcasl_enabled`).
 - Keys in `plugins` are the `PluginMeta.id` values.
 - `plugin_order` forces ordering and adjusts priority.
-- If `bcasl.yml` is missing, a default file is generated.
+- If `bcasl.yml` is missing, the workspace tools can generate a default file.
 - In plugin code, assume `bcasl.yml` lives at the workspace root.
 
 **Execution Context (PreCompileContext)**
 Key properties and methods.
 
-- `root`: Path object pointant vers la racine du workspace.
-- `name`: Nom du dossier workspace.
-- `config`: Dictionnaire complet de configuration (`bcasl.yml`).
-- `build_context`: Objet `BuildContext` contenant les paramètres de compilation (si disponible).
-- `file_patterns`: Patterns d'inclusion définis.
-- `exclude_patterns`: Patterns d'exclusion définis.
-- `iter_files(include, exclude)`: Itérateur optimisé (respecte les exclusions par défaut).
+- `root`: Path object pointing to the workspace root.
+- `name`: Workspace folder name.
+- `config`: Full `bcasl.yml` configuration dictionary.
+- `build_context`: `BuildContext` with compilation settings, when available.
+- `file_patterns`: Configured include patterns.
+- `exclude_patterns`: Configured exclude patterns.
+- `iter_files(include, exclude)`: Optimized iterator that respects exclusions by default.
 
-Usage du BuildContext :
+BuildContext usage:
 
 ```python
 def on_pre_compile(self, ctx: PreCompileContext) -> None:
     if ctx.build_context:
-        # Accès au dossier de sortie défini dans ark.yml ou le verrou
+        # Access the output directory defined in ark.yml or the lock file.
         output_dir = ctx.build_context.output_dir
         ...
 ```
 
-*Exemple concret : Le plugin **OutputCleaner** utilise `ctx.build_context.output_dir` pour vider le dossier de sortie avant la compilation.*
+*Example: the **OutputCleaner** plugin uses `ctx.build_context.output_dir` to clear the output directory before compilation.*
 
-Usage simplifié :
+Simplified usage:
 
 ```python
-# Parcourt tous les fichiers du projet selon la config bcasl.yml
+# Iterate over all project files using the bcasl.yml configuration.
 for path in ctx.iter_files():
     ...
 
-# Recherche spécifique tout en respectant les exclusions globales
+# Search specific files while still respecting global exclusions.
 for path in ctx.iter_files(["**/*.json"]):
     ...
 ```
@@ -180,8 +180,8 @@ ok = set_selected_workspace("/path/to/new/workspace")
 
 Behavior.
 
-- The request is accepted by contract (returns True).
-- The target directory is created if needed (best‑effort).
+- The request is accepted by contract (returns `True`).
+- The target directory is created if needed, best effort.
 - If the UI is present, the Core applies the change and may stop ongoing builds.
 - After requesting a switch, avoid using the old `ctx` for sensitive actions.
 
@@ -190,10 +190,10 @@ Behavior.
 - Use `Plugins_SDK.GeneralContext.Dialog` for messages and progress.
 - When running in the GUI, dialogs are routed through the UI thread and inherit the theme.
 - In headless/CLI mode, these are routed to standard output.
-- **Important**: Plugins should avoid direct Qt imports to remain compatible with headless execution. Direct Qt dialogs (like `QProgressDialog`) are not supported in sandboxed or headless runs.
+- **Important**: Avoid direct Qt imports to remain compatible with headless execution. Direct Qt dialogs such as `QProgressDialog` are not supported in sandboxed or headless runs.
 
 **Plugin UI Config Tabs**
-BCASL can expose per‑plugin configuration tabs in the BCASL config UI.
+BCASL can expose per-plugin configuration tabs in the BCASL config UI.
 
 Implement:
 
@@ -207,12 +207,13 @@ Notes.
 
 - `config` is a dict to read/write.
 - `on_save(config_dict)` can return an updated dict.
-- Saved under `plugins.<id>.config` in `bcasl.yml`.
+- Each plugin entry stores its config in the `config` field inside the `plugins` collection in `bcasl.yml`.
+- `build_config_tab(...)` may return a widget, a `(title, widget)` tuple, a `(title, widget, on_save)` tuple, or a dict with `title`, `widget`, and `on_save`.
 
 **Plugin i18n (GeneralContext)**
 Plugins can use the SDK i18n system with a `languages/` folder in the plugin package.
-The Core now propagates language changes to the Plugin SDK automatically, and the
-SDK loads translations for all plugins found in `Plugins/` (by folder name).
+The Core propagates language changes to the Plugin SDK, and the SDK loads
+translations for plugins found in `Plugins/` by folder name.
 
 Example layout:
 
@@ -224,7 +225,7 @@ Plugins/MyPlugin/
     fr.json
 ```
 
-Load and use (with live updates when the language changes):
+Load and use, with live updates when the language changes:
 
 ```python
 from Plugins_SDK.GeneralContext import (
@@ -251,10 +252,10 @@ Notes.
 
 - If `options.sandbox` is `true`, plugins can run in isolated processes.
 - Resource limits via `options.plugin_limits` (mem, cpu, files, size).
-- Note: Global timeout and parallelism are no longer supported to ensure sequential stability.
+- Note: global timeout and parallelism are no longer supported to keep execution sequential.
 
 **Plugins_SDK Utilities**
-The SDK provides many helpers.
+The SDK provides helpers for:
 
 - Project and Python file analysis.
 - Dependency and venv inspection.

docs/how_to_create_an_engine.md

@@ -10,7 +10,7 @@ A PyCompiler_ARK engine is a Python package placed in `engines/` and auto‑load
 
 - Engines are discovered only in `engines/<engine_id>/`.
 - The folder must contain an `__init__.py`.
-- At startup, `EngineLoader` scans `engines/` and imports each package.
+- Discovery is lazy: the registry loads engines on first real access such as `get_engine`, `available_engines`, `create`, or `bind_tabs`.
 - Auto discovery can be disabled with `ARK_ENGINES_AUTO_DISCOVER=0`.
 
 ### **Package Layout**
@@ -55,9 +55,12 @@ class MyEngine(CompilerEngine):
 
 ### **Workspace Entrypoint**
 
-The workspace can define a single build entrypoint in `ark.yml`.
-When `build.entrypoint` is set, the Core will compile only that file and pass it
-to your engine as the `entry_point` in the `BuildContext`. See `docs/ark.md`.
+The workspace defines its entrypoint in `ark.yml` under `project.entry`.
+That value is normalized by Core into `BuildContext.entry_point` and used as the
+primary script for compilation. A legacy `build.entrypoint` key is still accepted
+as a fallback during normalization, but `project.entry` is the canonical field.
+
+See `docs/ark_main_config.md`.
 
 ### **Full API**
 
@@ -98,8 +101,8 @@ Tools and dependencies.
 
 - In `create_tab`, create widgets and store them on `self` (ex: `self._opt_onefile`).
 - Avoid heavy work in `__init__` to keep loading fast.
-- Wire signals locally and use `gui.log.append(...)` for logs.
-- No need to wrap your tab in a scroll area: the UI handles large tabs automatically when needed.
+- Wire signals locally and prefer `gui.log.append(...)` for logs.
+- Do not add your own scroll area unless you need custom behavior; the host wraps large engine tabs automatically.
 - **IMPORTANT**: Do not include UI components for **Icon** selection or **Output directory** in your engine tab. These are globally managed in `ark.yml` and passed to your engine via the `BuildContext`. Focus only on engine‑specific flags and options.
 - Prefer grouping options with `QGroupBox` sections and compact hints, following the built-in engines layout style.
 - Keep widget attribute names stable once they are used by config persistence or compilation logic.
@@ -146,8 +149,7 @@ Notes.
 
 ### **Advanced Config Control (Special Engines)**
 
-Special engines can fully control where/how config is stored and whether the UI
-is allowed to save it.
+Special engines can override where config is stored and whether the UI may save it.
 
 New hooks:
 
@@ -158,8 +160,9 @@ New hooks:
 - `load_config(gui, workspace_dir) -> dict | None`: custom loader
 - `save_config(gui, workspace_dir, options) -> bool | None`: custom saver
 
-If a custom loader/saver returns `None`, Core falls back to the default
-`.ark/<engine_id>/config.json` behavior.
+If a custom loader returns `None`, Core falls back to the default
+`.ark/<engine_id>/config.json` behavior. A custom saver that returns `None`
+also falls back to the default storage path.
 
 #### Example: custom path + read‑only UI
 
@@ -348,14 +351,18 @@ Notes.
 - If a key is missing, always provide a safe fallback string.
 
 **Auto Command Builder (Integrated)**
-The auto‑builder is now integrated directly into the core compilation pipeline. It automatically reads a `mapping.json` in your engine's root directory to generate options from detected imports.
+The auto-builder is integrated into the core compilation pipeline. It can read
+`mapping.json` from the engine package, the workspace `engines/<engine_id>/`
+folder, or the `PYCOMPILER_MAPPING` environment variable to generate options
+from detected modules.
 
 You no longer need to call `compute_auto_for_engine` manually in your `build_command`. The core runner will:
 
-1. Detect modules imported in the project.
-2. Read your engine's `mapping.json`.
-3. Generate the appropriate flags.
-4. Automatically insert them into your command (usually before the entry point).
+1. Prefer `requirements.txt` or `requirements.in` when present.
+2. Fall back to `pyproject.toml` dependencies.
+3. Fall back to scanning Python imports.
+4. Read the engine mapping and generate the appropriate flags.
+5. Insert them into your command, usually before the entry point.
 
 #### **Minimal mapping.json example.**
 
@@ -374,10 +381,11 @@ You no longer need to call `compute_auto_for_engine` manually in your `build_com
 
 Key points.
 
-- Top‑level keys are package names.
+- Top-level keys are package names.
 - Engine values accept `str`, `list[str]`, or `dict` with `args` or `flags`.
-- `"{import_name}"` is replaced by the actual import name.
-- For advanced logic, expose `AUTO_BUILDER` in `engines/<engine_id>/auto_plugins.py`.
+- `"{import_name}"` is replaced by the matched import name.
+- For advanced logic, expose `AUTO_BUILDER`, `get_auto_builder()`, or
+  `register_auto_builder()` in `engines/<engine_id>/auto_plugins.py`.
 
 **Deep Examples Catalog (40)**
 Each example includes context, intent, and a working pattern. Adjust IDs and labels to match your engine.
@@ -795,7 +803,7 @@ def get_auto_builder():
 
 Notes.
 
-- Use when simple mapping is not enough.
+- Use this when simple mapping is not enough.
 
 1. mapping.json for torch (example).
 
@@ -820,7 +828,7 @@ Notes.
 1. Detection source (requirements preferred).
 
 ```python
-# Auto builder prioritizes requirements.txt when present
+# Auto-builder prioritizes `requirements.txt` or `requirements.in` when present.
 ```
 
 Notes.