Harden apex-flow skill for batch jobs, RSS, and VASP POTCAR uploads.

Add multi-structure config generation, disable non-TTY RSS tqdm by default, stage VASP POTCARs into job-relative paths, and tighten agent guidance for structure size and crystallographic planes.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: Zikkying

README.md

@@ -638,12 +638,32 @@ Property selection behavior:
 
 ### 4.5 Decohesive energy line
 
+Decohesive builds a rigid-separation series on one user-specified Miller plane via pymatgen `SlabGenerator`. It does **not** auto-enumerate planes (unlike `surface`) and has **no** crystal-type nested overrides (unlike `gamma`). Any structure that can form that slab is supported; set `miller_index` explicitly.
+
+Recommended default planes by crystal family (JSON `miller_index` uses **3-index** Miller notation):
+
+| Crystal structure | Recommended planes | JSON `miller_index` examples |
+|-------------------|--------------------|------------------------------|
+| **FCC** | $(100)$, $(110)$, $(111)$ | `[1,0,0]`, `[1,1,0]`, `[1,1,1]` |
+| **BCC** | $(100)$, $(110)$, $(111)$ | `[1,0,0]`, `[1,1,0]`, `[1,1,1]` |
+| **Diamond** | $(100)$, $(110)$, $(111)$ | `[1,0,0]`, `[1,1,0]`, `[1,1,1]` |
+| **Zinc blende** | $(100)$, $(110)$, $(111)$ | `[1,0,0]`, `[1,1,0]`, `[1,1,1]` |
+| **Rocksalt** | $(100)$, $(110)$, $(111)$ | `[1,0,0]`, `[1,1,0]`, `[1,1,1]` |
+| **HCP** | $(0001)$, $(10\bar{1}0)$, $(11\bar{2}0)$ | `[0,0,1]`, `[1,0,0]`, `[1,1,0]` |
+| **Perovskite** | $(001)$, $(110)$, $(111)$ | `[0,0,1]`, `[1,1,0]`, `[1,1,1]` |
+
+Notes:
+
+- HCP must use the **3-index** values above. Four-index Miller–Bravais vectors (e.g. `[0,0,0,1]`) are **not** accepted by `decohesive` (no Bravais conversion).
+- Polar / multi-termination faces (common for zinc blende $(111)$ and some perovskite cuts) still generate; APEX takes the first matching slab termination from pymatgen.
+- If the user does not specify a plane, prefer a low-index face from the table for the detected lattice and confirm before submit.
+
 | Key | Type | Example | Description |
 |-----|------|---------|-------------|
 | `min_slab_size` | Integer | `10` | Minimum slab thickness. |
 | `max_vacuum_size` | Integer | `11` | Maximum vacuum width. |
 | `pert_xz` | Float | `0.01` | Perturbation along xz plane for surface energy. |
-| `miller_miller` | List[Int] | `[1, 1, 0]` | Miller indices of the target plane. |
+| `miller_index` | List[Int] | `[1, 1, 0]` | Miller indices of the target plane (**required**, 3-index). |
 
 ### 4.6 Elastic
 

apex/rss.py

@@ -1,4 +1,5 @@
 import json
+import sys
 from pathlib import Path
 
 from pymatgen.core import Structure
@@ -18,6 +19,21 @@
 from apex.core.lib.rss import generate_rss, resolve_parent_lattice_auto
 
 
+def _resolve_show_progress(config: dict, stdout=None) -> bool:
+    """Resolve RSS progress-bar flag.
+
+    Explicit ``show_progress`` in rss.json always wins. Otherwise enable tqdm
+    only on an interactive TTY so agent/CI captured runs do not flood logs.
+    """
+    if "show_progress" in config:
+        return bool(config["show_progress"])
+    stream = sys.stdout if stdout is None else stdout
+    try:
+        return bool(stream.isatty())
+    except Exception:
+        return False
+
+
 def _jsonable(value):
     if isinstance(value, dict):
         result = {}
@@ -235,7 +251,7 @@ def run_rss_config(config_file: str) -> None:
         "allow_vacancies": config.get("allow_vacancies", False),
         "num_configs": config.get("num_configs", 1),
         "interval": config.get("interval", 100),
-        "show_progress": config.get("show_progress", True),
+        "show_progress": _resolve_show_progress(config),
         "patience": config.get("patience"),
         "return_metadata": write_metadata,
     }

apex/skills/apex-flow/SKILL.md

@@ -73,10 +73,17 @@ Options to offer via AskQuestion:
    (e.g. “用 EAM”, “用 ABACUS 做 EOS”, “用 DPA-3.2-5M-OMat24.pth”).
    **If AskQuestion times out or fails**: state the intended APEX backend and bundled model selection (if LAMMPS+DPA) in plain text and WAIT. Never silently submit.
 2. **STOP: Confirm property parameters before submission — DO NOT PROCEED WITHOUT USER ANSWER.** Before submitting, present the full `properties` configuration (JSON) to the user. Show the defaults that will be used and highlight:
-  - Miller indices (for surface/gamma/decohesive)
+  - Miller indices / slip systems (for surface/gamma/gamma_surface/decohesive)
   - Supercell sizes (for vacancy/interstitial/phonon/gruneisen/finite-T)
   - Temperature ranges (for finite_t_latt/finite_t_elastic/annealing)
   - Number of deformation/step points
+   For crystallographic planes:
+  - `gamma` / `gamma_surface`: pick from the canonical FCC/BCC/HCP table in
+    repository **README §4.10** (see also `reference/properties.md` §8–9). Do not
+    invent slip systems; do not silently change an approved plane/direction.
+  - `decohesive`: pick `miller_index` from the crystal-family table in
+    **README §4.5** / `reference/properties.md` §10 (FCC/BCC/Diamond/ZB/Rocksalt/
+    HCP/Perovskite). HCP must use **3-index** only.
    Let the user approve or modify. **Skip ONLY if** the user provided explicit property parameters already.
    **If AskQuestion times out or fails**: display the parameters in your message and WAIT for confirmation before submitting.
 3. **Two-layer architecture.** The outer Bohrium job is a thin submission client only. Never attempt `apex do` for production workflows — use `apex submit` which delegates to dflow. See `reference/submission.md` for the full architecture diagram.
@@ -97,6 +104,7 @@ Options to offer via AskQuestion:
 4. **Kill = inner FIRST, outer SECOND.** If you only kill the outer Bohrium node, the dflow workflow continues consuming resources silently. Always terminate the inner dflow workflow first. See `reference/workflow-control.md`.
 5. **MUST use `generate_config.py`; never hand-write `param.json` or `global.json`.**
   - Create the complete job with `python <skill-root>/scripts/generate_config.py create ...`.
+  - For multiple structures, pass repeated/space-separated `--structure` and/or `--structure-dir` to `create` (it copies each into `confs/<name>/` and fills `structures`); do not hand-edit `structures` after create.
   - To preserve an approved `param.json` while refreshing credentials, run
     `python <skill-root>/scripts/generate_config.py refresh-global --global global.json`
     from the task directory. This updates only `global.json`.
@@ -136,19 +144,42 @@ Options to offer via AskQuestion:
    (`scripts/fetch_models.py --source-checkpoint` or
    `dp --pt pretrained download DPA-3.2-5M`) and freeze that head before use.
    See `models/README.md`.
-11. **Preserve the user's input cell and prevent accidental double expansion.**
+11. **STOP: Check atom count / cell size before property submit — decide whether to expand.**
   APEX does not require a conventional cell. Do not convert a primitive cell or
    user-provided supercell to a conventional cell merely because an example uses
    `confs/std-fcc` or another `std-*` name.
-  - Inspect the supplied structure and determine whether it is already a supercell.
-  - If it is a supercell, ask whether the user wants any additional replication.
-  - If the answer is no, explicitly set applicable volumetric `supercell` or
-  `supercell_size` parameters to `[1, 1, 1]` so APEX does not expand it again.
+  Before confirming property parameters, **always read the user's structure** and
+  report: formula, atom count, lattice lengths, and whether it looks like a
+  primitive / conventional / already-expanded supercell.
+  Then decide with the user whether further bulk expansion is needed:
+  - **Too small for the property** (typical primitive or tiny conventional cell)
+    → recommend expanding; do not silently submit with an undersized cell.
+  - **Already large enough / already a supercell** → ask whether to expand again;
+    if no, set applicable volumetric `supercell` / `supercell_size` to `[1,1,1]`
+    so APEX does not expand twice.
   - Keep `elastic.conventional` false unless the user explicitly requests a
-  conventional-cell elastic calculation.
-  - Slab construction parameters for surface/gamma/decohesive calculations are
-  property geometry controls; confirm them separately rather than treating them
-  as generic bulk expansion.
+    conventional-cell elastic calculation.
+  - Slab properties (`surface` / `gamma` / `decohesive`) use `min_slab_size` /
+    in-plane replication, not bulk `supercell`; confirm those separately.
+  Use the helper wording and size guidance in
+  `reference/workflow-control.md` → **Pre-Submission Structure Validation**.
+12. **STOP: When the user gives a VASP POTCAR path, verify it and stage it into the job.**
+   Host libraries such as `/share/PAW_PBE/...` are **not** available inside
+   Bohrium/dflow containers. Leaving an absolute `potcar_prefix` in `param.json`
+   causes `FileNotFoundError: .../Ti_pv/POTCAR` after upload.
+   As soon as the user specifies a POTCAR library path:
+   1. Confirm the path exists and is readable locally.
+   2. Confirm every structure element has a POTCAR file under that library
+      (potpaw: prefer `"Ti": "Ti_pv/POTCAR"`).
+   3. Create the job with `generate_config.py create ... --potcar-prefix <lib>
+      --potcars 'Ti:Ti_pv/POTCAR,...'` — the script **copies** needed files into
+      `vasp_potcar/` and rewrites `potcar_prefix` to the relative `vasp_potcar`.
+   4. Verify `param.json` uses `"potcar_prefix": "vasp_potcar"` (not `/share/...`)
+      and that `vasp_potcar/<entry>` exists in the uploaded directory; then run
+      `validate_inputs.py`.
+   If the library is missing/incomplete: **STOP**, tell the user the path is
+   unusable, and ask for the correct POTCAR location. Never submit with an
+   absolute host POTCAR path hoping the container can see it.
 
 
 
@@ -230,7 +261,15 @@ See `reference/submission.md` for the full validated template.
 2. **Model files must be in job directory.** For MLIP workflows, the model file (`.pb`, `.pth`, `.model`, etc.) must be present in the submitted directory. Use relative paths in `param.json`. For DeePMD/DPA, copy `models/DPA-3.2-5M/DPA-3.2-5M-OMat24.pth`. Default to `"type_map": "auto"` for every LAMMPS interaction; specify a dictionary only when the user explicitly needs a fixed custom ordering.
 3. **Joint workflow recommended.** Use `joint` flow (relaxation + properties) for most use cases to ensure proper relaxation before property calculations.
 4. **GPU for ML potentials.** DeePMD, MACE, and NEP benefit from GPU acceleration. Set `scass_type` to a validated GPU SKU from `validate_apex_combo.py recommend --prefer gpu` (default: `"c8_m31_1 * NVIDIA T4"`).
-5. **Supercell sizing applies to unit-cell inputs only.** For defect calculations (vacancy, interstitial), a total cell equivalent to at least a [2,2,2] unit-cell expansion is normally needed. For phonon, [3,3,3] total size is recommended (phonoLAMMPS may fail with a smaller total cell). If the input is already a supercell and the user declines further expansion, use `[1,1,1]`; do not apply these factors again.
+5. **Supercell sizing depends on the input atom count, not only the default JSON.**
+   Treat defaults as targets for **unit-cell inputs**. First inspect the user's
+   structure; if it is already large enough, prefer `[1,1,1]` after confirmation.
+   Rough total-size guidance (after any expansion):
+   - vacancy / interstitial: ≳ [2,2,2] conventional-cell equivalent
+   - phonon / gruneisen / finite-T: ≳ [3,3,3] (smaller cells often fail)
+   - surface / gamma / decohesive: ensure slab thickness / in-plane size, not bulk supercell
+   If the cell is too small, ask the user to expand before submit. See
+   `reference/workflow-control.md`.
 6. **Outer job machine.** Use `c1_m2_cpu` for the outer Bohrium job since it only calls `apex submit` and waits. Don't waste larger CPU or GPU resources on the submission client.
 
 
@@ -243,6 +282,18 @@ structures before property calculations. Read `reference/rss_workflow.md`
 before asking the user questions or writing `rss.json`; it defines the required
 QA, current JSON schema, output layout, and visualization fallback.
 
+**Agent rules for RSS (mandatory):**
+- Always set `"show_progress": false` in `rss.json`. tqdm step bars (default
+  `max_steps=20000`) flood captured terminal output and waste context; do not
+  leave progress enabled “to see if it is working.”
+- After `apex rss`, judge success from files + metadata — not from live bars:
+  count `conf_*/POSCAR`, then read `rss_metadata.json` for convergence /
+  composition / duplicate warnings.
+- If zero configs are written, do **not** re-call `generate_rss` from Python to
+  bypass the CLI. Fix `rss.json` (`max_steps`, `interval`, `num_configs`,
+  compositions, cell size) and re-run `apex rss` once; report the metadata
+  diagnosis to the user.
+
 ## Working Test Case (Reference)
 
 Successfully validated workflow (ID: `cu-fcc-elastic-v3-joint-sdfml`):

apex/skills/apex-flow/reference/calculators.md

@@ -431,11 +431,11 @@ When `interaction.type` is `abacus` or `vasp`, the skill auto-applies smaller su
     "interaction": {
         "type": "vasp",
         "incar": "INCAR",
-        "potcar_prefix": "/path/to/POTCAR_LIBRARY",
+        "potcar_prefix": "vasp_potcar",
         "potcars": {
-            "Mo": "Mo_sv",
-            "Al": "Al",
-            "Fe": "Fe_pv"
+            "Mo": "Mo_sv/POTCAR",
+            "Al": "Al/POTCAR",
+            "Fe": "Fe_pv/POTCAR"
         }
     }
 }
@@ -485,15 +485,53 @@ LREAL = Auto
 
 ### VASP POTCAR Handling
 
-APEX expects POTCAR to be assembled from `potcar_prefix` using the element names in `potcars`. The directory structure should be:
+APEX concatenates files at:
+
+```text
+os.path.join(potcar_prefix, potcars[element])   # must be a readable FILE
 ```
+
+Typical VASP potpaw library layout and matching `potcars` values:
+
+```text
 /path/to/POTCAR_LIBRARY/
 ├── Mo_sv/POTCAR
 ├── Al/POTCAR
 ├── Fe_pv/POTCAR
 └── ...
 ```
 
+```json
+"potcar_prefix": "/path/to/POTCAR_LIBRARY",
+"potcars": {
+    "Mo": "Mo_sv/POTCAR",
+    "Al": "Al/POTCAR",
+    "Fe": "Fe_pv/POTCAR"
+}
+```
+
+Flat files also work (e.g. `"Mo": "POTCAR.Mo"` under `potcar_prefix`).
+
+### Agent check (mandatory when user supplies a POTCAR path)
+
+**Critical:** absolute host paths (e.g. `/share/PAW_PBE`) work only on that
+machine. After Bohrium/dflow upload they vanish →
+`FileNotFoundError: '/share/PAW_PBE/Ti_pv/POTCAR'`.
+
+Before submit:
+
+1. Confirm the user library exists and is readable locally.
+2. For each element, confirm a readable POTCAR file (prefer
+   `"Ti": "Ti_pv/POTCAR"` for potpaw trees).
+3. Use `generate_config.py create --potcar-prefix <lib> --potcars '...'` so
+   POTCARs are **copied** into the job as `vasp_potcar/` and `param.json` gets
+   `"potcar_prefix": "vasp_potcar"` (relative). Never ship absolute `/share/...`.
+4. Confirm the job directory contains `vasp_potcar/.../POTCAR` before upload.
+5. On failure: tell the user the path is unusable and ask for the correct
+   library. Do not guess.
+
+`scripts/validate_inputs.py` checks that staged relative POTCAR files exist.
+
 ---
 
 ## Backend Selection Guide

apex/skills/apex-flow/reference/examples.md

@@ -321,7 +321,8 @@ apex rss rss.json
 
 **Scenario**: Phonon band structure for Si using VASP.
 
-> ⚠️ Requires user to provide VASP image and POTCAR path.
+> ⚠️ Requires user to provide VASP image. Stage POTCARs into the job
+> (`vasp_potcar/`); do not leave absolute host paths like `/share/PAW_PBE`.
 
 ### param.json
 ```json
@@ -330,8 +331,8 @@ apex rss rss.json
     "interaction": {
         "type": "vasp",
         "incar": "INCAR",
-        "potcar_prefix": "/opt/vasp/potcar/PBE",
-        "potcars": {"Si": "Si"}
+        "potcar_prefix": "vasp_potcar",
+        "potcars": {"Si": "Si/POTCAR"}
     },
     "relaxation": {
         "cal_setting": {