Documentation: clarification sur build.exclude (packages uniquement) et typage des data

Author: raidos23

docs/ark_main_config.md

@@ -16,21 +16,61 @@ workspace:
   exclude:
     - ".git/**"
     - "venv/**"
+    - "**/__pycache__/**"
 
 build:
   engine: pyinstaller
   output: dist/
   icon: assets/icon.ico
   exclude:
-    - "tests/**"
+    - "tkinter"
+    - "unittest"
   data:
     - source: assets/
       destination: assets/
+      type: dir
+    - source: config.json
+      destination: config.json
+      type: file
 
 plugins:
   bcasl_enabled: true
 ```
 
+## Build Data Mappings
+
+The `build.data` section defines external files and directories to be bundled with the executable. Each entry must specify:
+
+- `source`: The relative path to the asset.
+- `destination`: The relative path where the asset will be placed in the final bundle.
+- `type`: Explicitly categorize the asset:
+    - `dir`: For entire directories.
+    - `file`: For single files.
+
+> **Note**: For backward compatibility, `type` defaults to `dir` if omitted, but explicit typing is highly recommended.
+
+## Build Exclusions vs Workspace Exclusions
+
+It is critical to distinguish between these two exclusion sections. Using them interchangeably is a common source of build failures.
+
+### 1. `workspace.exclude` (UI Filter)
+Used exclusively for the **GUI workspace view filter**. 
+- **Purpose**: Hide files and folders from the file list in the user interface.
+- **Usage**: Perfect for `.git/`, `venv/`, `__pycache__/`, or other technical folders you don't want to see in the GUI.
+
+### 2. `build.exclude` (Python Packages)
+Determines which **Python packages/modules** are ignored by the compiler.
+- **Purpose**: Prevent specific Python libraries from being bundled.
+- **Restriction**: This is **NOT** a general folder excluder. It should **NEVER** contain technical patterns like `*.pyc`, `__pycache__`, or `.git`. These are handled automatically by the Core or should be hidden via `workspace.exclude`.
+
+⚠️ **CRITICAL WARNING: Name Collisions**
+Patterns in `build.exclude` are passed to engines (like Nuitka or PyInstaller) as **logical module exclusions**. 
+
+If you have a local folder named `venv` (your virtual environment) and you add `venv` to `build.exclude` thinking you are excluding a directory, you are actually telling the compiler: *"Do not bundle the Python package named 'venv'"*. 
+If your project or any dependency uses `import venv` (the standard library), your application **will crash** because the library was removed from the bundle. 
+
+**Rule of thumb**: Only use `build.exclude` for real Python modules you want to remove (e.g., `tkinter`, `unittest`, or a specific large sub-package). For everything else, use `workspace.exclude`.
+
 ## Build Entrypoint
 
 `project.entry` defines the primary script to compile. It must be a path relative to the workspace root.

docs/dev_docs/PyCompiler_ARK_Locking_v1.2.md

@@ -48,14 +48,14 @@ project:
 
 workspace:
   exclude_patterns:        # Copied from build.exclude (legacy support)
-    - tests/**/*
-    - "**/__pycache__/**"
+    - tkinter
+    - unittest
 
 build:
   output: dist/            # Copied from build.output
   exclude:                 # Copied from build.exclude
-    - tests/**/*
-    - "**/__pycache__/**"
+    - tkinter
+    - unittest
   data:                    # Copied from build.data
     - source: assets/
       destination: assets/