zhyan0603 · zhyan0603 · Jul 4, 2026 · Jun 6, 2026 · Jun 11, 2026 · Jun 11, 2026
diff --git a/.gitignore b/.gitignore
@@ -16,6 +16,22 @@ build/
 .DS_Store
 Thumbs.db
 
+# Opencode
+.opencode
+
 # Temporary / generated files
 *.log
 temp_*.xyz
+
+# additional hygiene patterns
+*.tmp
+*.bak
+*~
+*.egg
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.omo/
+.claude/
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,38 @@
+# GPUMDkit
+
+GPUMDkit is a Bash + Python command-line toolkit for [GPUMD](https://gpumd.org/) and [NEP](https://gitlab.com/brucefan1983/nep) — molecular dynamics and neuroevolution potential programs. It provides format conversion, structure sampling, workflows, property calculation, plotting, and analysis utilities.
+
+**Entry point**: `gpumdkit.sh` — dual-mode (interactive menu + CLI flags):
+
+```bash
+gpumdkit.sh                                # Interactive mode
+gpumdkit.sh -h                             # Show all CLI flags
+gpumdkit.sh -plt train                     # Plot NEP training
+gpumdkit.sh -calc msd dump.xyz Li 10       # Calculate MSD
+gpumdkit.sh -dp2xyz database train.xyz     # DeepMD npy → extxyz
+```
+
+**Documentation**: https://zhyan0603.github.io/GPUMDkit/
+
+## Agent Skills
+
+When the user asks about GPUMDkit features, use the skills in `.opencode/skills/`:
+
+| Skill | Use When |
+|-------|----------|
+| `gpumdkit-main` | General usage, navigation, entry point |
+| `gpumdkit-format-conversion` | Converting structure files between formats |
+| `gpumdkit-calculators` | Computing material properties |
+| `gpumdkit-analyzers` | Analyzing structures and datasets |
+| `gpumdkit-visualization` | Plotting simulation data |
+| `gpumdkit-workflows` | Batch processing and automation |
+| `gpumdkit-sampling` | Sampling and selecting structures |
+
+## If You Need to Modify Code
+
+**Read [skills/gpumdkit-contributing/SKILL.md](skills/gpumdkit-contributing/SKILL.md) first.** It contains all coding conventions, function templates, shell/Python patterns, and explicit rejections (things NOT to propose). The project follows a strict minimum-invasion principle — do not touch working code unless fixing a confirmed bug.
+
+Key facts:
+- Tutorials are bilingual (`docs/tutorials/en/` + `zh/`). Feature changes must update both languages.
+- After Python edits: `python3 -m py_compile <file>` then clean `__pycache__`.
+- After doc edits: `mkdocs build -f docs/mkdocs.yml`.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,5 +1,10 @@
 # Contributing to GPUMDkit
 
+<p align="center">
+  <strong>English</strong>
+  &nbsp;·&nbsp;
+  <a href="./docs/CONTRIBUTING_zh-CN.md">简体中文</a>
+</p>
 
 Thank you for your interest in contributing to `GPUMDkit`! We appreciate your time and effort in helping improve this toolkit. `GPUMDkit` is an open-source package, and we welcome contributions from the community, whether you're fixing bugs, adding new features, improving documentation, or suggesting enhancements.
 
@@ -62,7 +67,9 @@ To maintain code quality and consistency across the project, please adhere to th
 ### Documentation
 
 - Ensure that help messages (e.g., `-h` flags) are clear and accurate.
-- Documentation files in the `docs/` directory will be updated by the maintainers, so you generally don't need to modify them.
+- Tutorial documentation lives in `docs/tutorials/en/` (English) and `docs/tutorials/zh/` (Chinese).
+  If you add a new feature, consider updating the relevant tutorial page.
+- After editing tutorial markdown files, rebuild the HTML with `mkdocs build -f docs/mkdocs.yml`.
 
 ---
 
@@ -124,7 +131,8 @@ Name your branch as you prefer.
 
 The structure of `GPUMDkit` consists of:
 - **`gpumdkit.sh`**: Main entry point (Bash script) handling both interactive menu mode and command-line mode
-- **`Scripts/`**: Python utility scripts organized by functionality
+- **`install.sh`**: Installation script that sets up environment variables and shell configuration
+- **`Scripts/`**: Python and Bash implementation scripts organized by functionality
   - `plt_scripts/`: Plotting scripts
   - `calculators/`: Calculation utilities
   - `format_conversion/`: Format conversion tools
@@ -140,7 +148,12 @@ The structure of `GPUMDkit` consists of:
   - `f5_analyzers.sh`
   - `f6_plots.sh`
   - `f7_utilities.sh`
+- **`skills/`**: AI agent skill definitions (SKILL.md files for opencode/Claude Code integration)
 - **`docs/`**: Documentation files
+  - `tutorials/en/` and `tutorials/zh/`: Bilingual tutorial pages
+  - `mkdocs.yml`: MkDocs configuration for building tutorial HTML
+  - `command_reference.tsv`: Machine-readable command reference
+  - `htmls/`: Generated HTML output from MkDocs
 
 #### Interactive Mode Contributions
 
@@ -163,18 +176,18 @@ To add a new feature accessible through the interactive menu:
 
    Add a new function:
    ```bash
-   function f106_new_converter(){
+   function f111_new_converter(){
    echo " >-------------------------------------------------<"
    echo " | Calling the script in Scripts/format_conversion |"
    echo " | Script: new_converter.py                        |"
    echo " | Developer: Your Name (your@email.com)           |"
    echo " >-------------------------------------------------<"
-   echo " Input the required parameters:"
-   echo " Examp: input.xyz output.lmp"
+   echo " Input <required_param1> <required_param2>"
+   echo " Example: input.xyz output.lmp"
    echo " ------------>>"
-   read -p " " converter_params
+   read -r -a converter_args
    echo " ---------------------------------------------------"
-   python ${GPUMDkit_path}/Scripts/format_conversion/new_converter.py ${converter_params}
+   python ${GPUMDkit_path}/Scripts/format_conversion/new_converter.py "${converter_args[@]}"
    echo " Code path: ${GPUMDkit_path}/Scripts/format_conversion/new_converter.py"
    echo " ---------------------------------------------------"
    }
@@ -185,7 +198,7 @@ To add a new feature accessible through the interactive menu:
    # Find the menu() function and update it if needed
    # Find the array_choice array and add your new choice number
    array_choice=(
-       "0" "1" "101" "102" "103" "104" "105" "106"  # Added "106"
+       "0" "1" "101" "102" "103" "104" "105" "106" "107" "108" "109" "110" "111"  # Added "111"
        # ... rest of choices
    )
    ```
@@ -199,9 +212,9 @@ To add a new feature accessible through the interactive menu:
            source ${GPUMDkit_path}/src/f1_format_conversions.sh
            case $choice in
                "1") f1_format_conversion ;;
-               "101") f101_out2xyz ;;
-               # ... existing cases ...
-               "106") f106_new_converter ;;  # Add your case
+                "101") f101_out2xyz ;;
+                # ... existing cases ...
+                "111") f111_new_converter ;;  # Add your case
            esac ;;
        # ...
    esac
@@ -222,36 +235,35 @@ To add a new command-line flag or subcommand:
    # Example: Scripts/analyzer/analyze_bonds.py
    import sys
 
-   def main():
-       if len(sys.argv) != 3:
-           print("Usage: gpumdkit.sh -analyze_bonds <input.xyz> <cutoff_distance>")
-           print("Example: gpumdkit.sh -analyze_bonds structure.xyz 3.0")
-           sys.exit(1)
-
-       input_file = sys.argv[1]
-       cutoff = float(sys.argv[2])
-
-       # Your implementation here
-
-   if __name__ == "__main__":
-       main()
+   if len(sys.argv) != 3:
+       print("Usage: gpumdkit.sh -analyze_bonds <input.xyz> <cutoff_distance>")
+       print("Example: gpumdkit.sh -analyze_bonds structure.xyz 3.0")
+       sys.exit(1)
+
+   input_file = sys.argv[1]
+   cutoff = float(sys.argv[2])
+
+   # Your implementation here
    ```
+
+   > **Note**: GPUMDkit Python scripts are designed to run directly (not imported as modules).
+   > You may use a `main()` function with `if __name__ == "__main__":` guard if you prefer,
+   > but it is not required. Most existing scripts execute at module level.
 
 3. **Add the command-line flag handler** in `gpumdkit.sh`:
    ```bash
-   # Find the command-line parsing section (after line ~167)
+   # Find the command-line parsing section (the large "case $1 in" block)
    # Add your new flag in the appropriate location
 
    case $1 in
        # ... existing cases ...
        -analyze_bonds)
-           if [ ! -z "$2" ] && [ ! -z "$3" ]; then
-               python ${analyzer_path}/analyze_bonds.py "$2" "$3"
+           if [ ! -z "$2" ] && [ "$2" != "-h" ] && [ ! -z "$3" ]; then
+               python ${analyzer_path}/analyze_bonds.py $2 $3
            else
                echo " Usage: gpumdkit.sh -analyze_bonds <input.xyz> <cutoff_distance>"
                echo " Example: gpumdkit.sh -analyze_bonds structure.xyz 3.0"
                echo " Code path: ${analyzer_path}/analyze_bonds.py"
-               exit 1
            fi ;;
        # ... rest of cases ...
    esac
@@ -279,17 +291,23 @@ vim Scripts/utils/completion.sh
 Add your new flag to the `opts` variable:
 ```bash
 # Find the line with local opts=...
-local opts="-h -update -U -help -clean -time -plt -calc -analyze_bonds -range -out2xyz ..."
-#                                                      ^^^^^^^^^^^^^^ Add your flag here
+local opts="-h -help -update -U -clean -time -plt -calc ... -your_new_flag ..."
+#                                                        Add your flag here
 ```
 
-If your flag accepts secondary options (like `-plt` or `-calc`), add a case for it:
+If your flag requires file arguments, add it to the existing file-completion case:
+```bash
+# Find the case for file-requiring flags and add yours with |
+-out2xyz|-out2exyz|-...|-your_new_flag)
+    COMPREPLY=($(compgen -f -- "$cur")) ;;
+```
+
+If your flag accepts secondary options (like `-plt` or `-calc`), add a new case:
 ```bash
 case "$prev" in
     # ... existing cases ...
-    -analyze_bonds)
-        COMPREPLY=($(compgen -f -- "$cur"))  # Complete with filenames
-        ;;
+    -your_new_flag)
+        COMPREPLY=($(compgen -W "option1 option2 option3" -- "$cur")) ;;
     # ... rest of cases ...
 esac
 ```
@@ -298,15 +316,53 @@ esac
 
 - **Shell Scripts**:
   - Use `${variable}` for variable expansion
-  - Write code that is clear and easy to maintain
+  - Use `[ ! -z "$var" ]` for non-empty checks (project convention)
+  - Interactive functions should follow the banner format:
+    ```bash
+    echo " >-------------------------------------------------<"
+    echo " | Calling the script in Scripts/<category>        |"
+    echo " | Script: <script_name>.py                        |"
+    echo " | Developer: <Name> (<email>)                     |"
+    echo " >-------------------------------------------------<"
+    ```
+  - Use `read -r -a varname` for multi-word input, then pass with `"${varname[@]}"`
+  - Shell scripts in `src/` should start with a file header block:
+    ```bash
+    # ============================================================
+    # GPUMDkit <module name> module
+    # Repository: https://github.com/zhyan0603/GPUMDkit
+    # Author: <Name> (<email>)
+    # ============================================================
+    ```
 
 - **Python Scripts**:
   - Write clear, maintainable code
   - Use meaningful variable names
+  - Use `sys.argv` for argument parsing (consistent with most existing scripts)
+  - Provide clear usage messages with `print("Usage: ...")` and `print("Example: ...")`
+  - If your script uses heavy/special packages (`NepTrain`, `calorine`, `dpdata`), add a
+    `print_dependency_notice()` function to inform users about citation recommendations
 
 ### Testing Your Changes
 
-Before submitting your contribution:
+Before submitting your contribution, run the relevant validation commands:
+
+```bash
+# Shell syntax checks (always run these)
+bash -n gpumdkit.sh
+find src Scripts -name '*.sh' -exec bash -n {} +
+
+# Python syntax checks (for modified Python files)
+python3 -m py_compile path/to/modified_script.py
+
+# MkDocs build (if you modified documentation)
+mkdocs build -f docs/mkdocs.yml
+
+# Check for trailing whitespace issues
+git diff --check
+```
+
+Then test functionality:
 
 1. **Test interactive mode** (if applicable):
    ```bash
@@ -345,10 +401,10 @@ Write clear, descriptive commit messages that explain what you changed. There ar
    git commit -m "your descriptive message"
    ```
 
-2. **Keep your branch updated** with the upstream `main` branch:
+2. **Keep your branch updated** with the latest `dev` branch:
    ```bash
-   git fetch upstream
-   git rebase upstream/main
+   git fetch origin
+   git rebase origin/dev
    ```
 
 3. **Push your branch** to your fork:

diff --git a/README.md b/README.md
@@ -4,10 +4,10 @@
 <p align="center">
   <strong>English</strong>
   &nbsp;·&nbsp;
-  <a href="./README_zh-CN.md">简体中文</a>
+  <a href="./docs/README_zh-CN.md">简体中文</a>
   &nbsp;·&nbsp;
   <a href="https://zhyan0603.github.io/GPUMDkit/">Website</a> &nbsp;·&nbsp;
-  <a href="https://zhyan0603.github.io/GPUMDkit/htmls/tutorials.html">Documentation</a>
+  <a href="https://zhyan0603.github.io/GPUMDkit/htmls/index.html">Documentation</a>
   &nbsp;·&nbsp;
   <a href="https://zhyan0603.github.io/GPUMDkit/gallery.html">Gallery</a>
   &nbsp;
@@ -102,15 +102,15 @@ There are two options, <u>*interactive mode*</u> and <u>*command-line mode*</u>
              | |_| |  __/| |_| | |  | | |_| |   <| | |_
               \____|_|    \___/|_|  |_|____/|_|\_\_|\__|
 
-              GPUMDkit Version 1.5.5 (dev) (2026-05-10)
+              GPUMDkit Version 1.5.6 (dev) (2026-06-17)
         Core Developer: Zihan YAN (yanzihan@westlake.edu.cn)
      Main Contributors: Denan LI, Xin WU, Zhoulin LIU & Chen HUA
 
      ---------------------- GPUMD ------------------------
      1) Format Conversion          2) Sample Structures
      3) Workflow                   4) Calculators
      5) Analyzer                   6) Visualization
-     7) Utilities                  8) Developing...
+     7) Utilities                  8) Help                
      0) Exit
      ------------>>
      Input the function number:
@@ -132,7 +132,7 @@ the help information:
 
 ```
 +-------------------------------------------------------------------------------------------------------+
-|                          GPUMDkit 1.5.5 (dev) (2026-05-10) Command Help                               |
+|                          GPUMDkit 1.5.6 (dev) (2026-06-17) Command Help                               |
 +-------------------------------------------------------------------------------------------------------+
 |                                          MAIN FUNCTIONS                                               |
 +-------------------------------------------------------------------------------------------------------+
@@ -158,8 +158,8 @@ the help information:
 | -chem_species Analyze chemical species        | -cbc               Charge balance check               |
 | -min_dist     Min distance (no PBC)           | -min_dist_pbc      Min distance with PBC              |
 | -filter_dist  Filter by min_dist (no PBC)     | -filter_dist_pbc   Filter by min_dist (PBC)           |
-| -pda          Probability density analysis    | -hbond             Hydrogen-bond analysis             |
-| -pynep        FPS sampling by PyNEP           |                                                       |
+| -pda          Probability density analysis    | -filter_box        Filter by box-edge length          |
+| -pynep        Deprecated PyNEP sampling       | -nep_modifier      Modify NEP model interactively     |
 +-------------------------------------------------------------------------------------------------------+
 | Detailed usage: gpumdkit.sh -<option> -h    Plot details: gpumdkit.sh -plt <type> -h                  |
 +-------------------------------------------------------------------------------------------------------+
@@ -175,7 +175,7 @@ the help information:
 
 ```
  +-----------------------------------------------------------------------------------------------+
- |                     GPUMDkit 1.5.5 (dev) (2026-05-10) PLOT & VISUALIZATION TOOLS              |
+ |                     GPUMDkit 1.5.6 (dev) (2026-06-17) PLOT & VISUALIZATION TOOLS              |
  +-----------------------------------------------------------------------------------------------+
  |  Usage: gpumdkit.sh -plt <type>                        Help: gpumdkit.sh -plt <type> -h       |
  +-----------------------------------------------------------------------------------------------+
@@ -265,13 +265,13 @@ You can also save images as PNG if your device doesn't support visualization:
 gpumdkit.sh -plt thermo save
 ```
 
-Refer to our [documentation](https://zhyan0603.github.io/GPUMDkit/htmls/tutorials.html) for more detailed examples and command options.
+Refer to our [documentation](https://zhyan0603.github.io/GPUMDkit/) for more detailed examples and command options.
 
 #### Custom Commands
 
 `GPUMDkit` now supports custom commands via `~/.gpumdkit.in`.
 
-You can add your own shortcuts (e.g., `gpumdkit.sh -yourcommand`) by defining some functions in this file. This allows you to extend `GPUMDkit` with personal scripts. See [here](https://zhyan0603.github.io/GPUMDkit/htmls/custom_commands.html) for the detail usage.
+You can add your own shortcuts (e.g., `gpumdkit.sh -yourcommand`) by defining functions in this file. This allows you to extend `GPUMDkit` with personal scripts. See [custom command documentation](https://zhyan0603.github.io/GPUMDkit/) for details.
 
 #### Tab Completion Support
 
@@ -297,4 +297,8 @@ Also, welcome to join our QQ group ([825696376](https://qun.qq.com/universal-sha
 
 **GPUMDkit** is an open-source tool freely available for everyone. If you find it helpful in your research or workflow, please ⭐ [star us on GitHub](https://github.com/zhyan0603/GPUMDkit). Additionally, if GPUMDkit contributes to your published work, please cite our paper:
 
-> Z. Yan\*, D. Li, X. Wu, Z. Liu, C. Hua, B. Situ, H. Yang, S. Tang, B. Tang, Z. Wang, S. Yi, H. Wang, D. Huang, K. Li, Q. Guo, Z. Chen, K. Xu, Y. Wang, Z. Wang, G. Tang, S. Liu, Z. Fan, and Y. Zhu\*. **GPUMDkit: A User-Friendly Toolkit for GPUMD and NEP**. [MGE Advances, 2026, e70074](https://doi.org/10.1002/mgea.70074). 
+> Z. Yan\*, D. Li, X. Wu, Z. Liu, C. Hua, B. Situ, H. Yang, S. Tang, B. Tang, Z. Wang, S. Yi, H. Wang, D. Huang, K. Li, Q. Guo, Z. Chen, K. Xu, Y. Wang, Z. Wang, G. Tang, S. Liu, Z. Fan, and Y. Zhu\*. **GPUMDkit: A User-Friendly Toolkit for GPUMD and NEP**. [MGE Advances, 2026, 4, e70074](https://doi.org/10.1002/mgea.70074).
+
+In your manuscript you may write something like:
+
+> Data processing and figure generation were performed using GPUMDkit [x].