feat: update README and README_ZH to reflect advanced features and improvements in obfuscation engine

Author: for13to1

README.md

@@ -10,182 +10,153 @@
 [![English](https://img.shields.io/badge/English-README-blue)](README.md)
 [![中文](https://img.shields.io/badge/中文-README_ZH-red)](README_ZH.md)
 
-Mistode (Mist Code, pronounced like "Miss Told") is a lightweight code obfuscation tool supporting Python and C. It focuses on making code difficult to read while maintaining functional integrity.
+Mistode (Mist Code, pronounced like *miss-told*) is a lightweight, advanced code obfuscation tool protecting **Python** and **C** source code. It combines robust AST/Regex parsing with a distributed layout engine to ensure code is unreadable yet fully functional and perfectly restorable.
 
 ## Features
 
-- **Encrypted Token Generator**: Highly customizable encrypted token generation supporting various configurations:
-  - **Random Seed**: Supports setting a random seed to ensure reproducibility.
-  - **Length Control**: Custom token length, range [8, 32] characters.
-  - **Style Configuration**: Supports two obfuscation styles:
-    - **Similar Character Style**: Uses visually similar character groups to enhance obfuscation (e.g., `Oo0`, `iIlL1`, `b6B8`, `Zz2`, `Ss5`).
-    - **Random Character Style**: Uses random alphanumeric combinations.
-  - **Smart Deduplication**: Automatically maintains a set of generated tokens to avoid duplicates.
-- **Python Support**:
-  - **AST Parsing**: Accurate obfuscation based on Abstract Syntax Trees, ensuring complete preservation of code format.
-  - **Smart Identifier Classification**: Automatically identifies and preserves imported modules, functions, and built-in methods.
-  - **Docstring Obfuscation**: Replaces docstrings with hash values.
-  - **Fully Reversible**: Supports full restoration using generated key files or embedded metadata.
-  - **Lossless Restoration**: Achieves lossless consistency with the original file (preserving all comments and formatting) via distributed annotated injection of source chunks.
-- **C Support**:
-  - **Fast Tokenization**: Uses robust regular expression tokenizers.
-  - **Layout Engine**: Uses `// @mistode:chunk:` metadata to preserve code structure.
-  - **Compilation Safety**: Preserves keywords, preprocessor directives, and external symbols.
-  - **Lossless Restoration**: Achieves lossless consistency with the original file via distributed layout chunks.
+- **🛡️ Advanced Obfuscation Engine**:
+  - **Encrypted Token Generation**: Configurable token length (8-32 chars) and styles (Similar Characters like `Oo01Il` or Random Alphanumeric).
+  - **Smart Deduplication & Validation**: Ensures no collisions and validates generated tokens against language keywords.
+  - **Seed Support**: Fully reproducible obfuscation with `--seed`.
 
-## Installation
-
-```shell
-pip install mistode
-```
+- **🐍 Python Support (v3.14+)**:
+  - **AST-Based Precision**: Parses the Abstract Syntax Tree for safe and accurate transformation.
+  - **Smart Preservation**: Automatically protects imports, built-ins (`print`, `len`), and standard library calls.
+  - **Docstring Hashing**: Replaces docstrings with unique hash markers.
 
-## Usage
+- **🇨 C Support**:
+  - **Robust Tokenization**: Regex-based engine safely handling macros, pointers, and structs.
+  - **Layout Engine**: Preserves complex file structures using distributed `// @mistode:chunk:` markers.
+  - **Symbol Safety**: Automatically preserves keywords, preprocessor directives, and standard headers.
 
-### Simple Usage (Default Settings)
+- **🔄 Zero-Loss Restoration**:
+  - **Distributed Source Chunks**: The original source is compressed, encrypted, and distributed throughout the obfuscated file as comments.
+  - **Embedded Metadata**: Identifier mappings are embedded directly in the file header/footer. **No key file is required for restoration.**
+  - **Bit-Perfect Restore**: Restores every byte of the original code, including comments, formatting, and empty lines.
 
-```shell
-# Obfuscate (generates input.obf.py and input.map.json)
-mistode o input.py
+- **⚙️ Modern Tooling**:
+  - **Configuration File**: Global defaults via `pyproject.toml`.
+  - **Detailed Statistics**: `--stats` flag provides identifier counts, compression ratios, and safety checks.
 
-# Restore (automatically detects input.map.json if naming matches)
-# Generates input.res.py
-mistode r input.obf.py
-```
-
-### Full Usage
+## Installation
 
-```shell
-# Obfuscate with explicit options
-mistode obfuscate input.py --out output.py --key mapping.json
+> [!IMPORTANT]
+> Mistode requires **Python 3.14** or higher.
 
-# Restore with explicit options
-mistode restore output.py --out restored.py --key mapping.json
+```bash
+pip install mistode
 ```
 
-### Configuration File
+## Quick Start
 
-You can set default options in `pyproject.toml` to avoid repeating the same arguments:
+### 1. Python Example
 
-```toml
-[tool.mistode]
-style = "similar"    # Default obfuscation style ("similar" or "random")
-length = 16          # Default token length (8-32)
-stats = true         # Always show statistics
-# seed = 42          # Optional: set a default seed for reproducibility
-```
+```bash
+# Obfuscate 'app.py' (generates app.obf.py)
+mistode o app.py --stats
 
-**How it works**:
+# Restore to original (generates app.res.py)
+# No key file needed - uses embedded metadata!
+mistode r app.obf.py
 
-- Mistode automatically searches for `pyproject.toml` in the current directory and parent directories
-- If found, settings from `[tool.mistode]` are used as defaults
-- Command-line arguments always override configuration file settings
+# Verify match
+diff app.py app.res.py
+```
 
-**Example**:
+### 2. C Example
 
 ```bash
-# With the config above, these are equivalent:
-mistode o input.py
-mistode o input.py --style similar --length 16 --stats
+# Obfuscate 'main.c' (generates main.obf.c)
+mistode o main.c --stats
+
+# Compile and run obfuscated code
+gcc main.obf.c -o main_obf
+./main_obf
 
-# Override config with command-line args:
-mistode o input.py --style random --length 20
+# Restore
+mistode r main.obf.c
 ```
 
-For a complete guide, see [`examples/CONFIG_GUIDE.md`](examples/CONFIG_GUIDE.md).
+## Usage Guide
 
-## Advanced Features
+### Command Line Interface
 
-### Smart Identifier Recognition for Python Obfuscation
+```bash
+# General Syntax
+mistode [command] [file] [options]
 
-Mistode intelligently identifies and avoids obfuscating the following types of identifiers:
+# Commands
+o, obf, obfuscate   Obfuscate a file
+r, res, restore     Restore a file
+```
 
-- **Built-in Modules**: `re`, `os`, `sys`, `json`, `math`, etc.
-- **Built-in Functions**: `print`, `len`, `range`, `str`, `int`, etc.
-- **Imported Functions**: Functions imported via `import` and `from ... import` statements.
-- **Built-in Methods**: `re.sub`, `str.strip`, `list.append`, etc.
+### Common Options
 
-### Example
+| Option | Alias | Description |
+| :--- | :--- | :--- |
+| `--out` | `-o` | Specify output filename. |
+| `--key` | `-k` | Specify key file path (optional, as metadata is embedded). |
+| `--stats` | | Show detailed statistics after processing. |
+| `--style` | | `similar` (default) or `random`. |
+| `--length` | `-l` | Token length (8-32). |
+| `--seed` | `-s` | Random seed for reproducibility. |
+| `--password` | `-p` | Password for encryption/decryption. |
 
-**Original Code**:
+### Configuration File (`pyproject.toml`)
 
-```python
-import re
-from openpyxl.utils import get_column_letter, column_index_from_string
+You can define project-wide defaults in `pyproject.toml`. Mistode automatically looks for this file in the current and parent directories.
 
-def shift_column_letter(base_column, offset):
-    """Calculate the shifted column letter based on the given column letter and offset"""
-    base_idx = column_index_from_string(base_column)
-    target_idx = base_idx + offset
-    return get_column_letter(target_idx)
+```toml
+[tool.mistode]
+style = "similar"    # "similar" (Io01) or "random" (aB3d)
+length = 24          # Stronger tokens
+stats = true         # Always show stats
+seed = 12345         # Deterministic builds
 ```
 
-**Obfuscated Code**:
+For a detailed guide, see [examples/CONFIG_GUIDE.md](examples/CONFIG_GUIDE.md).
 
-```python
-import re
-from openpyxl.utils import get_column_letter, column_index_from_string
+## What Gets Obfuscated?
 
-#@mistode:chunk:eJzjSklNU8hIzcnJ11BQyEvMTVVQ0LTiU...
-def Oo0iIlL1b6B8Zz2Ss5(Oo0iIlL1b6B8Zz2Ss6, Oo0iIlL1b6B8Zz2Ss7):
-    """Obfuscated docstring: e2d30883ac53"""
-#@mistode:chunk:aVaCikKXmAdOkoVEO01SopaCoogFWAiQo...
-    Oo0iIlL1b6B8Zz2Ss8 = column_index_from_string(Oo0iIlL1b6B8Zz2Ss6)
-    Oo0iIlL1b6B8Zz2Ss9 = Oo0iIlL1b6B8Zz2Ss8 + Oo0iIlL1b6B8Zz2Ss7
-    return get_column_letter(Oo0iIlL1b6B8Zz2Ss9)
-#@mistode:metadata:eJxVk1Fr3DAMx79K...
-```
+### Python
 
-### Embedded Metadata & Distributed Source
+| Component | Status | Notes |
+| :--- | :---: | :--- |
+| **Variable Names** | ✅ | Replaced with tokens |
+| **Function/Class Names** | ✅ | Replaced with tokens |
+| **Docstrings** | ✅ | Replaced with hash placeholders |
+| **Imports** | ❌ | Preserved (`import math`) |
+| **Built-ins** | ❌ | Preserved (`print`, `len`) |
+| **Stdlib Methods** | ❌ | Preserved (`os.path.join`) |
 
-Mistode uses a two-layer restoration mechanism:
+### C / C++
 
-1. **Distributed Source Chunks (`#@mistode:chunk:` or `// @mistode:chunk:`)**: The original source code is compressed, encoded, and injected as chunks before each line of the obfuscated code. Restoration prioritizes these chunks to reconstruct the original code, achieving **lossless restoration** (including all comments, empty lines, and formatting).
-2. **Embedded Metadata (`#@mistode:metadata:`)**: Contains the identifier mapping table as a backup restoration method.
+| Component | Status | Notes |
+| :--- | :---: | :--- |
+| **Functions** | ✅ | User-defined only |
+| **Variables/Structs** | ✅ | Local and Global |
+| **Comments** | ✅ | Scrambled or Removed |
+| **Keywords** | ❌ | Preserved (`if`, `while`) |
+| **Preprocessor** | ❌ | Preserved (`#include`, `#define`) |
+| **Std Lib** | ❌ | Preserved (`printf`, `malloc`) |
 
-This means you can perfectly restore the original code even without keeping the key file.
+## Restoration Mechanics
 
-```python
-# ... Obfuscated Code ...
-#@mistode:chunk:eJzjSk... (Distributed Source Chunk)
-# ...
-#@mistode:metadata:eJxVk1... (Base64 Encoded Mapping)
-```
+Mistode uses a **dual-layer restoration system** to guarantee safety:
 
-If no key file is provided, the restore command automatically detects and uses this metadata.
-
-## Project Structure
-
-```shell
-mistode/
-├── src/
-│   └── mistode/
-│       ├── __init__.py      # Package Initialization
-│       ├── cli.py           # Command Line Interface
-│       ├── python.py        # Python Obfuscator (mistode.python)
-│       ├── c.py             # C Obfuscator (mistode.c)
-│       └── core.py          # Core Functionality (mistode.core)
-├── tests/                   # Tests Directory
-│   ├── __init__.py
-│   ├── test_python.py       # Python Obfuscator Tests
-│   ├── test_c.py            # C Obfuscator Tests
-│   ├── test_cli.py          # CLI Tests (Integration)
-│   ├── test_cli_unit.py     # CLI Tests (Unit)
-│   └── test_core.py         # Core Functionality Tests
-├── pyproject.toml           # Project Configuration
-└── README.md                # Project Documentation
-```
+1. **Distributed Source Chunks (Primary)**:
+    Chunks of the compressed original source are injected as comments (e.g., `#@mistode:chunk:...`) throughout the file. This allows **100% bit-perfect restoration**.
 
-## Development
+2. **Embedded Mappings (Secondary)**:
+    The renaming map is compressed and embedded in the file footer (`#@mistode:metadata:`). If chunks are damaged, this allows functional restoration.
 
-### Running Tests
+3. **Key File (Optional)**:
+    You can explicitly save the mapping to a JSON file with `--key`, but it is not required for standard workflows.
 
-```shell
-python -m pytest tests/
-```
+## Contributing
 
-### Building the Package
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
 
-```shell
-pip install build
-python -m build
-```
+## License
+
+This project is licensed under the [GPLv3 License](LICENSE).