diff --git a/docs/apps/apply/battery.md b/docs/apps/apply/battery.md
index 38cc035..b711db9 100644
--- a/docs/apps/apply/battery.md
+++ b/docs/apps/apply/battery.md
@@ -4,7 +4,7 @@ title: Battery Explorer
 
 # Battery Explorer
 
-Battery cathode voltage profile and theoretical capacity predictor. Supports model selection: default_path or wt01_path. Uses ALIGNN-FF for intercalation energy calculations.
+Predict battery cathode voltage profiles and theoretical capacity using ALIGNN force-field. Sequentially removes intercalating ions from a supercell, computes energy at each step with ALIGNN-FF, and builds the voltage vs. ion-fraction curve. Supports 6 ion types (Li, Na, K, Mg, Ca, Zn) and 2 ALIGNN-FF models (default, wt01).
 
 [:material-open-in-new: Open App](https://atomgpt.org/battery){ .md-button .md-button--primary }
 
@@ -12,50 +12,188 @@ Battery cathode voltage profile and theoretical capacity predictor. Supports mod
 
 ## Overview
 
-Battery cathode voltage profile and theoretical capacity predictor. Supports model selection: default_path or wt01_path. Uses ALIGNN-FF for intercalation energy calculations.
+The Battery Explorer takes a cathode POSCAR structure, creates a supercell (enforced ~8 Å c-axis), identifies all intercalating ion sites, then sequentially removes ions one at a time. At each step, the total energy is computed with ALIGNN-FF (`AlignnAtomwiseCalculator`). The voltage at each step is:
+
+**V = E(n+1) − E(n) + μ_element**
+
+where μ_element is the per-atom energy of the elemental reference (e.g., BCC Li). Theoretical gravimetric (mAh/g) and volumetric (mAh/cm³) capacities are computed from the composition and Faraday's constant.
 
 !!! info "Data Source"
-    **ALIGNN-FF battery models**
+    **ALIGNN-FF** (`default_path` or `wt01_path`) for energy calculations.
+    **JARVIS-DFT** elemental reference energies from `jarvis.analysis.thermodynamics.energetics.get_optb88vdw_energy()`.
 
 ## Endpoints
 
-- `GET /battery`
-- `POST /battery/predict`
-
-**Request Models:** `BatteryPredictRequest`
+### `POST /battery/predict` — Voltage profile + capacity
 
-!!! note "Authentication"
-    All POST endpoints require `Authorization: Bearer YOUR_TOKEN`.
+Predict the full voltage profile and theoretical capacity for a cathode material. Takes a POSCAR structure, intercalating ion, and model selection.
 
-## API Example
+```bash
+curl -X POST "https://atomgpt.org/battery/predict" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "poscar": "LiO2Co\n1.0\n2.719 -0.003 4.091\n1.234 2.423 4.091\n-0.004 -0.003 4.913\nLi Co O\n1 1 2\nCartesian\n1.974 1.209 6.548\n0.0 0.0 0.0\n1.027 0.629 3.405\n2.922 1.789 9.690",
+    "element": "Li",
+    "model": "default"
+  }'
+```
 
-```python
-import requests
-
-response = requests.post(
-    "https://atomgpt.org/battery/predict",
-    headers={
-        "Authorization": "Bearer sk-XYZ",
-        "accept": "application/json",
-        "Content-Type": "application/json",
-    },
-    json={"jid": "JVASP-1002"},
-)
-data = response.json()
-print(data)
+Na-ion battery example:
+
+```bash
+curl -X POST "https://atomgpt.org/battery/predict" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "poscar": "NaCoO2\n1.0\n2.89 0.0 0.0\n-1.445 2.502 0.0\n0.0 0.0 10.83\nNa Co O\n1 1 2\nDirect\n0.0 0.0 0.25\n0.0 0.0 0.0\n0.0 0.0 0.117\n0.0 0.0 0.883",
+    "element": "Na",
+    "model": "default"
+  }'
 ```
 
-## AGAPI Agent
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `poscar` | string | required | VASP POSCAR of cathode structure (must contain the intercalating ion) |
+| `element` | string | `"Li"` | Intercalating ion: `"Li"`, `"Na"`, `"K"`, `"Mg"`, `"Ca"`, or `"Zn"` |
+| `model` | string | `"default"` | ALIGNN-FF model: `"default"` or `"wt01"` |
+
+**Response:**
+
+| Field | Description |
+|-------|-------------|
+| `compositions` | Ion fraction array (normalized 0→1) |
+| `voltages` | Cell voltage at each step (eV) |
+| `energies` | Total energy at each step (eV) |
+| `n_steps` | Number of ion removal steps |
+| `gravimetric_capacity` | Theoretical gravimetric capacity (mAh/g) |
+| `volumetric_capacity` | Theoretical volumetric capacity (mAh/cm³) |
+| `density` | Material density (g/cm³) |
+| `molar_mass` | Molar mass (g/mol) |
+| `formula` | Reduced chemical formula |
+| `spacegroup` | Space group |
+| `charge` | Ion oxidation state |
+| `result_text` | Human-readable summary with CSV data |
+
+---
+
+## Python Examples
+
+=== "Li-ion cathode"
+
+    ```python
+    import requests
+
+    LICOO2 = """LiO2Co
+    1.0
+    2.719 -0.003 4.091
+    1.234 2.423 4.091
+    -0.004 -0.003 4.913
+    Li Co O
+    1 1 2
+    Cartesian
+    1.974 1.209 6.548
+    0.0 0.0 0.0
+    1.027 0.629 3.405
+    2.922 1.789 9.690"""
+
+    response = requests.post(
+        "https://atomgpt.org/battery/predict",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={
+            "poscar": LICOO2,
+            "element": "Li",
+            "model": "default",
+        },
+    )
+    data = response.json()
+    if data["success"]:
+        print(f"{data['formula']} — {data['element']}+ cathode")
+        print(f"  Gravimetric: {data['gravimetric_capacity']} mAh/g")
+        print(f"  Volumetric:  {data['volumetric_capacity']} mAh/cm³")
+        print(f"  Steps: {data['n_steps']}")
+        for c, v in zip(data["compositions"], data["voltages"]):
+            print(f"  x={c:.3f}  V={v:.3f} eV")
+    ```
+
+=== "Plot voltage profile"
+
+    ```python
+    import requests
+    import matplotlib.pyplot as plt
+
+    response = requests.post(
+        "https://atomgpt.org/battery/predict",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={
+            "poscar": open("LiCoO2.vasp").read(),
+            "element": "Li",
+        },
+    )
+    data = response.json()
+
+    plt.figure(figsize=(8, 5))
+    plt.plot(data["compositions"], data["voltages"], "o-", color="#f59e0b", lw=2)
+    plt.xlabel("Li fraction")
+    plt.ylabel("Voltage (eV)")
+    plt.title(f"{data['formula']} — {data['gravimetric_capacity']} mAh/g")
+    plt.grid(alpha=0.3)
+    plt.tight_layout()
+    plt.savefig("voltage_profile.png")
+    ```
+
+=== "Compare ions"
+
+    ```python
+    import requests
+
+    POSCAR = open("cathode.vasp").read()
+
+    for ion in ["Li", "Na", "K"]:
+        response = requests.post(
+            "https://atomgpt.org/battery/predict",
+            headers={
+                "Authorization": "Bearer sk-XYZ",
+                "accept": "application/json",
+                "Content-Type": "application/json",
+            },
+            json={"poscar": POSCAR, "element": ion},
+        )
+        data = response.json()
+        if data["success"]:
+            avg_v = sum(data["voltages"]) / len(data["voltages"])
+            print(f"{ion}: {data['gravimetric_capacity']} mAh/g, avg V={avg_v:.2f} eV")
+    ```
+
+## AGAPI Agent [WIP]
 
 ```python
 from agapi.agents import AGAPIAgent
 import os
 
 agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
-response = agent.query_sync("Show battery explorer for Silicon")
+
+# Predict voltage profile
+response = agent.query_sync("Predict the Li-ion voltage profile for LiCoO2")
+print(response)
+
+# Compare models
+response = agent.query_sync("Compare default and wt01 ALIGNN-FF for LiCoO2 battery cathode")
 print(response)
 ```
 
-## Reference
+## References
 
-- Comp. Mat. Sci. 259, 114063 (2025)
+- K. Choudhary, Digital Discovery 2(2), 346 (2023) — ALIGNN-FF [:material-link: DOI](https://doi.org/10.1039/D2DD00096B)
+- K. Choudhary, Comp. Mat. Sci. 259, 114063 (2025) [:material-link: DOI](https://doi.org/10.1016/j.commatsci.2025.114063)
+- [atomgptlab/alignn](https://github.com/atomgptlab/alignn)
diff --git a/docs/apps/apply/catalysis.md b/docs/apps/apply/catalysis.md
index 89622f5..d43cb37 100644
--- a/docs/apps/apply/catalysis.md
+++ b/docs/apps/apply/catalysis.md
@@ -4,7 +4,7 @@ title: Catalysis
 
 # Catalysis
 
-Predict adsorption energy of a molecule on a substrate using ALIGNN-FF. Input: substrate POSCAR + catalyst (substrate+adsorbate) POSCAR + adsorbate indices. Computes E_ads = E_cat - E_sub - E_mol.
+Predict adsorption energy of a molecule on a substrate surface using ALIGNN force-field. Provide the clean substrate POSCAR and the substrate+adsorbate POSCAR, specify which atoms are the adsorbate (1-indexed), and the app computes E_ads = E_cat − E_sub + μ(adsorbate). Chemical potentials are from JARVIS DFT elemental reference energies. Supports default and wt01 ALIGNN-FF models.
 
 [:material-open-in-new: Open App](https://atomgpt.org/catalysis){ .md-button .md-button--primary }
 
@@ -12,50 +12,203 @@ Predict adsorption energy of a molecule on a substrate using ALIGNN-FF. Input: s
 
 ## Overview
 
-Predict adsorption energy of a molecule on a substrate using ALIGNN-FF. Input: substrate POSCAR + catalyst (substrate+adsorbate) POSCAR + adsorbate indices. Computes E_ads = E_cat - E_sub - E_mol.
+The Catalysis app computes adsorption energies without running full DFT. It uses ALIGNN-FF (`AlignnAtomwiseCalculator`) to evaluate the total energy of both the clean substrate and the substrate+adsorbate system, then combines them with JARVIS elemental chemical potentials:
+
+**E_ads = E_catalyst − E_substrate + μ(adsorbate atoms)**
+
+where μ is the sum of per-atom elemental reference energies from `jarvis.analysis.thermodynamics.energetics.get_optb88vdw_energy()`. Negative E_ads indicates exothermic (favorable) adsorption.
 
 !!! info "Data Source"
-    **ALIGNN-FF**
+    **ALIGNN-FF** (`default_path` or `wt01_path`) for energy calculations.
+    **JARVIS-DFT** elemental reference chemical potentials.
 
 ## Endpoints
 
-- `GET /catalysis`
-- `POST /catalysis/predict`
-
-**Request Models:** `CatalysisPredictRequest`
+### `POST /catalysis/predict` — Compute adsorption energy
+
+Takes two POSCAR structures (substrate and catalyst) plus adsorbate atom indices. Computes energies with ALIGNN-FF and returns the adsorption energy breakdown.
+
+```bash
+curl -X POST "https://atomgpt.org/catalysis/predict" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "substrate": "Substrate\n1.0\n5.882 0.0 0.0\n2.941 5.094 0.0\n0.0 0.0 22.203\nAg Au\n12 4\ndirect\n0.0 0.0 0.338\n0.5 0.0 0.338\n0.0 0.5 0.338\n0.5 0.5 0.338\n0.167 0.167 0.446\n0.667 0.167 0.446\n0.167 0.667 0.446\n0.667 0.667 0.446\n-0.167 0.333 0.554\n0.333 0.333 0.554\n-0.167 0.833 0.554\n0.333 0.833 0.554\n0.0 0.0 0.662\n0.5 0.0 0.662\n0.0 0.5 0.662\n0.5 0.5 0.662",
+    "catalyst": "Catalyst,adsorbate_indices:[17]\n1.0\n5.882 0.0 0.0\n2.941 5.094 0.0\n0.0 0.0 22.203\nAg Au O\n12 4 1\ndirect\n0.0 0.0 0.338\n0.5 0.0 0.338\n0.0 0.5 0.338\n0.5 0.5 0.338\n0.167 0.167 0.446\n0.667 0.167 0.446\n0.167 0.667 0.446\n0.667 0.667 0.446\n-0.167 0.333 0.554\n0.333 0.333 0.554\n-0.167 0.833 0.554\n0.333 0.833 0.554\n0.0 0.0 0.662\n0.5 0.0 0.662\n0.0 0.5 0.662\n0.5 0.5 0.662\n0.0 0.0 0.743",
+    "adsorbate_indices": [17],
+    "model": "default"
+  }'
+```
 
-!!! note "Authentication"
-    All POST endpoints require `Authorization: Bearer YOUR_TOKEN`.
+Multi-atom adsorbate (CO on Cu):
+
+```bash
+curl -X POST "https://atomgpt.org/catalysis/predict" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "substrate": "Cu\n1.0\n3.615 0.0 0.0\n0.0 3.615 0.0\n0.0 0.0 3.615\nCu\n4\ndirect\n0.0 0.0 0.0\n0.0 0.5 0.5\n0.5 0.0 0.5\n0.5 0.5 0.0",
+    "catalyst": "Cu,adsorbate_indices:[5,6]\n1.0\n3.615 0.0 0.0\n0.0 3.615 0.0\n0.0 0.0 3.615\nCu C O\n4 1 1\ndirect\n0.0 0.0 0.0\n0.0 0.5 0.5\n0.5 0.0 0.5\n0.5 0.5 0.0\n0.0 0.0 0.2\n0.0 0.0 0.35",
+    "adsorbate_indices": [5, 6],
+    "model": "default"
+  }'
+```
 
-## API Example
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `substrate` | string | required | POSCAR of clean substrate (no adsorbate) |
+| `catalyst` | string | required | POSCAR of substrate + adsorbate |
+| `adsorbate_indices` | list[int] | required | 1-indexed atom positions of adsorbate in catalyst POSCAR |
+| `model` | string | `"default"` | ALIGNN-FF model: `"default"` or `"wt01"` |
+
+!!! tip "Auto-detection"
+    The web UI auto-detects adsorbate indices from the POSCAR comment line format `adsorbate_indices:[17]`.
+
+**Response:**
+
+| Field | Description |
+|-------|-------------|
+| `adsorption_energy` | E_ads (eV) — negative = exothermic |
+| `substrate_energy` | E_substrate from ALIGNN-FF (eV) |
+| `catalyst_energy` | E_catalyst from ALIGNN-FF (eV) |
+| `chemical_potential` | Sum of elemental μ for adsorbate atoms (eV) |
+| `chemical_potential_details` | Per-element breakdown |
+| `formula_substrate` | Reduced formula of substrate |
+| `formula_catalyst` | Reduced formula of catalyst |
+| `adsorbate_elements` | List of adsorbate element symbols |
+| `result_text` | Human-readable summary |
 
-```python
-import requests
-
-response = requests.post(
-    "https://atomgpt.org/catalysis/predict",
-    headers={
-        "Authorization": "Bearer sk-XYZ",
-        "accept": "application/json",
-        "Content-Type": "application/json",
-    },
-    json={"jid": "JVASP-1002"},
-)
-data = response.json()
-print(data)
-```
+---
 
-## AGAPI Agent
+## Python Examples
+
+=== "O on AgAu surface"
+
+    ```python
+    import requests
+
+    SUBSTRATE = """Substrate
+    1.0
+    5.882 0.0 0.0
+    2.941 5.094 0.0
+    0.0 0.0 22.203
+    Ag Au
+    12 4
+    direct
+    0.0 0.0 0.338
+    0.5 0.0 0.338
+    0.0 0.5 0.338
+    0.5 0.5 0.338
+    0.167 0.167 0.446
+    0.667 0.167 0.446
+    0.167 0.667 0.446
+    0.667 0.667 0.446
+    -0.167 0.333 0.554
+    0.333 0.333 0.554
+    -0.167 0.833 0.554
+    0.333 0.833 0.554
+    0.0 0.0 0.662
+    0.5 0.0 0.662
+    0.0 0.5 0.662
+    0.5 0.5 0.662"""
+
+    CATALYST = """Catalyst,adsorbate_indices:[17]
+    1.0
+    5.882 0.0 0.0
+    2.941 5.094 0.0
+    0.0 0.0 22.203
+    Ag Au O
+    12 4 1
+    direct
+    0.0 0.0 0.338
+    0.5 0.0 0.338
+    0.0 0.5 0.338
+    0.5 0.5 0.338
+    0.167 0.167 0.446
+    0.667 0.167 0.446
+    0.167 0.667 0.446
+    0.667 0.667 0.446
+    -0.167 0.333 0.554
+    0.333 0.333 0.554
+    -0.167 0.833 0.554
+    0.333 0.833 0.554
+    0.0 0.0 0.662
+    0.5 0.0 0.662
+    0.0 0.5 0.662
+    0.5 0.5 0.662
+    0.0 0.0 0.743"""
+
+    response = requests.post(
+        "https://atomgpt.org/catalysis/predict",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={
+            "substrate": SUBSTRATE,
+            "catalyst": CATALYST,
+            "adsorbate_indices": [17],
+            "model": "default",
+        },
+    )
+    data = response.json()
+    if data["success"]:
+        sign = "exothermic" if data["adsorption_energy"] < 0 else "endothermic"
+        print(f"E_ads = {data['adsorption_energy']} eV ({sign})")
+        print(f"  E_sub  = {data['substrate_energy']} eV")
+        print(f"  E_cat  = {data['catalyst_energy']} eV")
+        print(f"  μ(ads) = {data['chemical_potential']} eV")
+        print(f"  Adsorbate: {data['adsorbate_elements']}")
+    ```
+
+=== "Compare adsorbates"
+
+    ```python
+    import requests
+
+    PT_SUB = open("Pt_substrate.vasp").read()
+
+    for ads_file, indices in [("Pt_H.vasp", [5]), ("Pt_O.vasp", [5]), ("Pt_CO.vasp", [5, 6])]:
+        cat = open(ads_file).read()
+        response = requests.post(
+            "https://atomgpt.org/catalysis/predict",
+            headers={
+                "Authorization": "Bearer sk-XYZ",
+                "accept": "application/json",
+                "Content-Type": "application/json",
+            },
+            json={
+                "substrate": PT_SUB,
+                "catalyst": cat,
+                "adsorbate_indices": indices,
+            },
+        )
+        data = response.json()
+        if data["success"]:
+            ads = "+".join(data["adsorbate_elements"])
+            print(f"Pt + {ads}: E_ads = {data['adsorption_energy']:.3f} eV")
+    ```
+
+## AGAPI Agent [WIP]
 
 ```python
 from agapi.agents import AGAPIAgent
 import os
 
 agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
-response = agent.query_sync("Show catalysis for Silicon")
+
+# Predict adsorption
+response = agent.query_sync("Predict the adsorption energy of O on AgAu surface using ALIGNN-FF")
 print(response)
 ```
 
-## Reference
+## References
 
-- Comp. Mat. Sci. 259, 114063 (2025)
+- K. Choudhary, Comp. Mat. Sci. 259, 114063 (2025) [:material-link: DOI](https://doi.org/10.1016/j.commatsci.2025.114063)
+- J. Catal. 442, 116171 (2025) — CatalysisMat [:material-link: DOI](https://doi.org/10.1016/j.jcat.2025.116171)
+- K. Choudhary, Digital Discovery 2(2), 346 (2023) — ALIGNN-FF [:material-link: DOI](https://doi.org/10.1039/D2DD00096B)
+- [atomgptlab/catalysismat](https://github.com/atomgptlab/catalysismat)
+- [atomgptlab/alignn](https://github.com/atomgptlab/alignn)
diff --git a/docs/apps/apply/dac.md b/docs/apps/apply/dac.md
index 8b08937..b8c61b6 100644
--- a/docs/apps/apply/dac.md
+++ b/docs/apps/apply/dac.md
@@ -4,7 +4,7 @@ title: Direct Air Capture
 
 # Direct Air Capture
 
-Direct Air Capture CO₂ Isotherm Predictor using ALIGNN pretrained on hMOF data. Uses alignn.pretrained.get_figshare_model to auto-download the model.
+Predict CO₂ adsorption isotherms for metal-organic frameworks (MOFs) using ALIGNN trained on the hypothetical MOF (hMOF) dataset. Outputs CO₂ uptake at 5 pressure points (0.01, 0.05, 0.1, 0.5, 2.5 bar) from a single POSCAR input. The model (`hmof_co2_absp_alignn`) is auto-downloaded from figshare on first use.
 
 [:material-open-in-new: Open App](https://atomgpt.org/dac){ .md-button .md-button--primary }
 
@@ -12,38 +12,123 @@ Direct Air Capture CO₂ Isotherm Predictor using ALIGNN pretrained on hMOF data
 
 ## Overview
 
-Direct Air Capture CO₂ Isotherm Predictor using ALIGNN pretrained on hMOF data. Uses alignn.pretrained.get_figshare_model to auto-download the model.
+The DAC app uses a specialized ALIGNN model with 5 output features, each corresponding to CO₂ adsorption (mol/kg) at a different pressure point. The model was trained on the hMOF dataset of ~130K hypothetical metal-organic frameworks with GCMC-computed CO₂ isotherms. Input any MOF crystal structure as POSCAR and get the predicted isotherm in seconds.
 
 !!! info "Data Source"
-    **ALIGNN hMOF model**
+    **ALIGNN** model `hmof_co2_absp_alignn` — auto-downloaded from figshare via `alignn.pretrained.get_figshare_model()`.
+    Trained on the hMOF dataset (hypothetical MOFs with GCMC CO₂ isotherms).
 
 ## Endpoints
 
-- `GET /dac`
-- `POST /dac/predict`
+### `POST /dac/predict` — Predict CO₂ isotherm from POSCAR
 
-**Request Models:** `DACPredictRequest`
+```bash
+curl -X POST "https://atomgpt.org/dac/predict" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "poscar": "ZIF-8\n1.0\n-8.496 8.496 8.496\n8.496 -8.496 8.496\n8.496 8.496 -8.496\nZn N H C\n6 24 96 48\ndirect\n0.75 0.25 0.5\n0.25 0.75 0.5\n0.5 0.75 0.25\n0.5 0.25 0.75\n0.25 0.5 0.75\n0.75 0.5 0.25\n0.651 0.093 0.378\n0.714 0.273 0.622\n0.286 0.907 0.559\n0.349 0.727 0.441\n0.378 0.651 0.093\n0.622 0.714 0.273\n0.559 0.286 0.907\n0.441 0.349 0.727\n0.093 0.378 0.651\n0.273 0.622 0.714\n0.907 0.559 0.286\n0.727 0.441 0.349\n0.093 0.651 0.378\n0.273 0.714 0.622\n0.907 0.286 0.559\n0.727 0.349 0.441\n0.651 0.378 0.093\n0.714 0.622 0.273\n0.286 0.559 0.907\n0.349 0.441 0.727\n0.378 0.093 0.651\n0.622 0.273 0.714\n0.559 0.907 0.286\n0.441 0.727 0.349"
+  }'
+```
 
-!!! note "Authentication"
-    All POST endpoints require `Authorization: Bearer YOUR_TOKEN`.
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `poscar` | string | required | VASP POSCAR of MOF structure (max 50KB) |
 
-## API Example
+**Response:**
 
-```python
-import requests
-
-response = requests.post(
-    "https://atomgpt.org/dac/predict",
-    headers={
-        "Authorization": "Bearer sk-XYZ",
-        "accept": "application/json",
-        "Content-Type": "application/json",
-    },
-    json={"jid": "JVASP-1002"},
-)
-data = response.json()
-print(data)
-```
+| Field | Description |
+|-------|-------------|
+| `pressures` | `[0.01, 0.05, 0.1, 0.5, 2.5]` (bar) |
+| `adsorption` | Predicted CO₂ uptake at each pressure (mol/kg) |
+| `pressure_unit` | `"bar"` |
+| `adsorption_unit` | `"mol/kg"` |
+| `formula` | Reduced chemical formula |
+| `num_atoms` | Number of atoms |
+| `spacegroup` | Space group |
+
+---
+
+## Python Examples
+
+=== "Predict isotherm"
+
+    ```python
+    import requests
+
+    ZIF8 = open("ZIF-8.vasp").read()
+
+    response = requests.post(
+        "https://atomgpt.org/dac/predict",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={"poscar": ZIF8},
+    )
+    data = response.json()
+    if data["success"]:
+        print(f"{data['formula']} ({data['num_atoms']} atoms)")
+        for p, a in zip(data["pressures"], data["adsorption"]):
+            print(f"  {p:>5.2f} bar → {a:.5f} mol/kg")
+    ```
+
+=== "Plot isotherm"
+
+    ```python
+    import requests
+    import matplotlib.pyplot as plt
+
+    response = requests.post(
+        "https://atomgpt.org/dac/predict",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={"poscar": open("MOF.vasp").read()},
+    )
+    data = response.json()
+
+    plt.figure(figsize=(7, 5))
+    plt.semilogx(data["pressures"], data["adsorption"], "o-", color="#22c55e", lw=2, ms=8)
+    plt.xlabel("Pressure (bar)")
+    plt.ylabel("CO₂ Adsorption (mol/kg)")
+    plt.title(f"{data['formula']} — CO₂ Isotherm (ALIGNN)")
+    plt.grid(alpha=0.3)
+    plt.tight_layout()
+    plt.savefig("co2_isotherm.png")
+    ```
+
+=== "Screen multiple MOFs"
+
+    ```python
+    import requests
+    import glob
+
+    results = []
+    for f in glob.glob("mofs/*.vasp"):
+        response = requests.post(
+            "https://atomgpt.org/dac/predict",
+            headers={
+                "Authorization": "Bearer sk-XYZ",
+                "accept": "application/json",
+                "Content-Type": "application/json",
+            },
+            json={"poscar": open(f).read()},
+        )
+        data = response.json()
+        if data["success"]:
+            # Adsorption at 0.5 bar (index 3)
+            results.append((data["formula"], data["adsorption"][3]))
+
+    results.sort(key=lambda x: x[1], reverse=True)
+    print("Top MOFs by CO₂ uptake at 0.5 bar:")
+    for formula, ads in results[:10]:
+        print(f"  {formula}: {ads:.4f} mol/kg")
+    ```
 
 ## AGAPI Agent
 
@@ -52,10 +137,15 @@ from agapi.agents import AGAPIAgent
 import os
 
 agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
-response = agent.query_sync("Show direct air capture for Silicon")
+
+# Predict isotherm
+response = agent.query_sync("Predict the CO2 adsorption isotherm for ZIF-8")
 print(response)
 ```
 
-## Reference
+## References
 
-- Comp. Mat. Sci. 259, 114063 (2025)
+- Kamal Choudhary, Taner Yildirim, Daniel W Siderius, A Gilad Kusne, Austin McDannald, Diana L Ortiz-Montalvo, Comp. Mat. Sci. 210, 111388 (2022) [:material-link: DOI](https://www.sciencedirect.com/science/article/pii/S092702562200163X)
+- K. Choudhary, Comp. Mat. Sci. 259, 114063 (2025) [:material-link: DOI](https://doi.org/10.1016/j.commatsci.2025.114063)
+- K. Choudhary, npj Comp. Mat. 7, 185 (2021) — ALIGNN [:material-link: DOI](https://doi.org/10.1038/s41524-021-00650-1)
+- [atomgptlab/alignn](https://github.com/atomgptlab/alignn)
diff --git a/docs/apps/apply/solar.md b/docs/apps/apply/solar.md
index 9959287..1181de8 100644
--- a/docs/apps/apply/solar.md
+++ b/docs/apps/apply/solar.md
@@ -4,7 +4,7 @@ title: Solar Cell Screening
 
 # Solar Cell Screening
 
-Predict theoretical solar cell performance: SLME (spectroscopic limited maximum efficiency) and Shockley-Queisser limit. Uses jarvis.analysis.solarefficiency.solar.SolarEfficiency directly. Input by JID or upload absorption data.
+Predict theoretical solar cell performance using SLME (spectroscopic limited maximum efficiency) and Shockley-Queisser (SQ) limit. Two modes: (1) input a JARVIS ID to download TBmBJ vasprun.xml and compute SLME + SQ + J-V curves automatically, (2) input custom band gaps and absorption coefficient data for SLME calculation.
 
 [:material-open-in-new: Open App](https://atomgpt.org/solar){ .md-button .md-button--primary }
 
@@ -12,51 +12,191 @@ Predict theoretical solar cell performance: SLME (spectroscopic limited maximum
 
 ## Overview
 
-Predict theoretical solar cell performance: SLME (spectroscopic limited maximum efficiency) and Shockley-Queisser limit. Uses jarvis.analysis.solarefficiency.solar.SolarEfficiency directly. Input by JID or upload absorption data.
+The Solar Cell Screening app uses `jarvis.analysis.solarefficiency.solar.SolarEfficiency` to compute theoretical photovoltaic performance. For JARVIS materials, it downloads the TBmBJ vasprun.xml from figshare, extracts direct/indirect band gaps and the average absorption coefficient, then sweeps film thickness (1nm–5μm) to find the optimal SLME. It also computes the SQ efficiency limit and full J-V / P-V curves at the optimal thickness.
 
 !!! info "Data Source"
-    **dft_3d + jarvis.analysis.solarefficiency**
+    **JARVIS TBmBJ** — vasprun.xml files from `jarvis.db.figshare.data('raw_files')['TBMBJ']`.
+    **AM1.5G** solar spectrum from JARVIS package.
 
 ## Endpoints
 
-- `GET /solar`
-- `POST /solar/predict-jid`
-- `POST /solar/predict-data`
+### `POST /solar/predict-jid` — SLME + SQ from JARVIS ID
 
-**Request Models:** `SolarJidRequest`, `SolarDataRequest`
+Downloads the TBmBJ vasprun.xml for the given JARVIS ID, extracts band gaps and absorption coefficient, computes SLME efficiency vs thickness, finds the optimal thickness, and returns SQ efficiency + J-V curves.
 
-!!! note "Authentication"
-    All POST endpoints require `Authorization: Bearer YOUR_TOKEN`.
+```bash
+curl -X POST "https://atomgpt.org/solar/predict-jid" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "jid": "JVASP-1002"
+  }'
+```
+
+```bash
+curl -X POST "https://atomgpt.org/solar/predict-jid" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "jid": "JVASP-1067"
+  }'
+```
 
-## API Example
+**Response** includes:
+
+| Field | Description |
+|-------|-------------|
+| `dirgap` | Direct band gap (eV) |
+| `indirgap` | Indirect band gap (eV) |
+| `optimal_thickness` | Optimal film thickness (m) |
+| `optimal_efficiency` | SLME at optimal thickness (%) |
+| `sq_efficiency` | Shockley-Queisser limit (%) |
+| `thickness` | Array of thickness values (m) |
+| `efficiencies` | SLME at each thickness (%) |
+| `V` | Voltage array for J-V curve |
+| `JV` | Current density array (A/m²) |
+| `PV` | Power density array (W/m²) |
+| `optimal_voltage` | Voltage at max power (V) |
+| `J_sc` | Short-circuit current density (A/m²) |
 
-```python
-import requests
-
-response = requests.post(
-    "https://atomgpt.org/solar/predict-jid",
-    headers={
-        "Authorization": "Bearer sk-XYZ",
-        "accept": "application/json",
-        "Content-Type": "application/json",
-    },
-    json={"jid": "JVASP-1002"},
-)
-data = response.json()
-print(data)
+---
+
+### `POST /solar/predict-data` — SLME from custom absorption data
+
+Compute SLME from user-provided band gaps and absorption coefficient data. Requires at least 5 data points.
+
+```bash
+curl -X POST "https://atomgpt.org/solar/predict-data" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "indirect_gap": 1.1,
+    "direct_gap": 3.4,
+    "temperature": 293.15,
+    "energies": [0.5, 1.0, 1.5, 2.0, 2.5, 3.0, 3.5, 4.0, 4.5, 5.0],
+    "absorptions": [0, 0, 100, 5000, 20000, 50000, 80000, 100000, 120000, 150000]
+  }'
 ```
 
-## AGAPI Agent
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `indirect_gap` | float | required | Indirect band gap (eV) |
+| `direct_gap` | float | required | Direct band gap (eV) |
+| `temperature` | float | 293.15 | Temperature (K) |
+| `energies` | list[float] | required | Photon energy array (eV) |
+| `absorptions` | list[float] | required | Absorption coefficient array (cm⁻¹) |
+
+**Response** same as `/predict-jid` — thickness sweep, optimal SLME, SQ limit, J-V curves.
+
+---
+
+## Python Examples
+
+=== "Predict by JID"
+
+    ```python
+    import requests
+
+    response = requests.post(
+        "https://atomgpt.org/solar/predict-jid",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={"jid": "JVASP-1002"},
+    )
+    data = response.json()
+    if data["success"]:
+        print(f"Direct gap: {data['dirgap']:.3f} eV")
+        print(f"Indirect gap: {data['indirgap']:.3f} eV")
+        print(f"SLME: {data['optimal_efficiency']:.2f}%")
+        print(f"SQ limit: {data['sq_efficiency']:.2f}%")
+        print(f"Optimal thickness: {data['optimal_thickness']*1e6:.2f} μm")
+        print(f"J_sc: {data['J_sc']:.2f} A/m²")
+    ```
+
+=== "Custom absorption data"
+
+    ```python
+    import requests
+
+    response = requests.post(
+        "https://atomgpt.org/solar/predict-data",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={
+            "indirect_gap": 1.1,
+            "direct_gap": 3.4,
+            "temperature": 300.0,
+            "energies": [0.5, 1.0, 1.5, 2.0, 2.5, 3.0, 3.5, 4.0],
+            "absorptions": [0, 0, 100, 5000, 20000, 50000, 80000, 100000],
+        },
+    )
+    data = response.json()
+    if data["success"]:
+        print(f"SLME: {data['optimal_efficiency']:.2f}%")
+        print(f"SQ limit: {data['sq_efficiency']:.2f}%")
+    ```
+
+=== "Plot J-V curve"
+
+    ```python
+    import requests
+    import matplotlib.pyplot as plt
+
+    response = requests.post(
+        "https://atomgpt.org/solar/predict-jid",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={"jid": "JVASP-1002"},
+    )
+    data = response.json()
+
+    fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(12, 4))
+    ax1.plot(data["V"], data["JV"])
+    ax1.set_xlabel("Voltage (V)")
+    ax1.set_ylabel("Current density (A/m²)")
+    ax1.set_title("J-V curve")
+
+    ax2.plot([t * 1e6 for t in data["thickness"]], data["efficiencies"])
+    ax2.set_xlabel("Thickness (μm)")
+    ax2.set_ylabel("SLME (%)")
+    ax2.set_title(f"SLME vs thickness (opt: {data['optimal_efficiency']:.1f}%)")
+    plt.tight_layout()
+    plt.savefig("solar_jvasp1002.png")
+    ```
+
+## AGAPI Agent [WIP]
 
 ```python
 from agapi.agents import AGAPIAgent
 import os
 
 agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
-response = agent.query_sync("Show solar cell screening for Silicon")
+
+# Predict by JID
+response = agent.query_sync("Compute the solar cell efficiency for JVASP-1002")
+print(response)
+
+# Compare materials
+response = agent.query_sync("Compare the SLME of JVASP-1002 and JVASP-1067")
 print(response)
 ```
 
-## Reference
+## References
 
-- Comp. Mat. Sci. 259, 114063 (2025)
+- K. Choudhary, Comp. Mat. Sci. 259, 114063 (2025) [:material-link: DOI](https://doi.org/10.1016/j.commatsci.2025.114063)
+- K. Choudhary, F. Tavazza, Chem. Mater. 31, 5900 (2019) — Accelerated Discovery of Efficient Solar Cell Materials [:material-link: DOI](https://doi.org/10.1021/acs.chemmater.9b02166)
+- K. Choudhary et al., Nature Sci. Data 5, 180082 (2018) — JARVIS-DFT [:material-link: DOI](https://doi.org/10.1038/sdata.2018.82)
+- C. Ginter, K. Choudhary, S. Mandal, arXiv:2510.08738 (2025) [:material-link: arXiv](https://arxiv.org/abs/2510.08738)
+- [atomgptlab/jarvis](https://github.com/atomgptlab/jarvis)
diff --git a/docs/apps/apply/supercon.md b/docs/apps/apply/supercon.md
index c875448..ca3cd2c 100644
--- a/docs/apps/apply/supercon.md
+++ b/docs/apps/apply/supercon.md
@@ -4,7 +4,7 @@ title: SuperconGPT
 
 # SuperconGPT
 
-3 tabs: (1) Inverse design — generate crystal structures for target Tc using AtomGPT, (2) Database search for known superconductors, (3) Predict Tc for any structure with ALIGNN.
+Three-tab superconductor discovery platform: (1) Inverse design — generate crystal structures for a target Tc using AtomGPT, optionally relax with ALIGNN-FF and predict properties, (2) Database search — query SuperconDB (1058 3D + 161 2D materials + hydrides) by elements with α²F(ω) Eliashberg function plots, (3) Tc predictor — predict superconducting Tc and 7 other properties from any POSCAR using ALIGNN.
 
 [:material-open-in-new: Open App](https://atomgpt.org/supercon){ .md-button .md-button--primary }
 
@@ -12,53 +12,239 @@ title: SuperconGPT
 
 ## Overview
 
-3 tabs: (1) Inverse design — generate crystal structures for target Tc using AtomGPT, (2) Database search for known superconductors, (3) Predict Tc for any structure with ALIGNN.
+SuperconGPT combines generative AI (AtomGPT) for inverse design of superconductors with a curated DFT-based BCS superconductor database and ALIGNN property prediction. The database includes Tc, electron-phonon coupling constant λ, logarithmic phonon frequency ω_log, α²F(ω) Eliashberg functions, and stability information for ambient-pressure 3D and 2D superconductors.
 
 !!! info "Data Source"
-    **dft_3d + AtomGPT + ALIGNN supercon model**
+    **SuperconDB 3D** (1058 entries) + **SuperconDB 2D** (161 entries) + hydrides from [`jarvis.db.figshare`](https://atomgptlab.github.io/jarvis/databases/).
+    **AtomGPT** (SuperconGPT LoRA adapter) for inverse crystal generation.
+    **ALIGNN** (`jv_supercon_tc_alignn`) for Tc prediction.
 
 ## Endpoints
 
-- `GET /supercon`
-- `POST /supercon/generate`
-- `GET /supercon/generate`
-- `GET /supercon/search`
-- `POST /supercon/predict_tc`
+### `POST /supercon/generate` — Inverse design: generate structure for target Tc
+
+Generate a crystal structure for a given chemical formula and target superconducting Tc using AtomGPT. Optionally relax with ALIGNN-FF and run ALIGNN property predictions.
+
+```bash
+curl -X POST "https://atomgpt.org/supercon/generate" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "formula": "MgB2",
+    "tc": 39.0,
+    "max_new_tokens": 512,
+    "temperature": 0.0,
+    "top_k": 50,
+    "top_p": 1.0,
+    "do_sample": false,
+    "relax": false,
+    "run_alignn": true
+  }'
+```
 
-**Request Models:** `SuperconGenerateRequest`, `SuperconPredictRequest`
 
-!!! note "Authentication"
-    All POST endpoints require `Authorization: Bearer YOUR_TOKEN`.
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `formula` | string | required | Chemical formula (e.g. `"MgB2"`, `"LaH10"`, `"H3S"`) |
+| `tc` | float | required | Target superconducting Tc in Kelvin |
+| `max_new_tokens` | int | 512 | Max generation tokens (64–2048) |
+| `temperature` | float | 0.0 | Sampling temperature (0 = deterministic) |
+| `top_k` | int | 50 | Top-K sampling (1–500) |
+| `top_p` | float | 1.0 | Nucleus sampling threshold |
+| `do_sample` | bool | false | Enable stochastic sampling |
+| `relax` | bool | false | Relax generated structure with ALIGNN-FF |
+| `run_alignn` | bool | false | Run ALIGNN property predictions on result |
 
-## API Example
+**Response** includes `poscar`, `formula_generated`, `spacegroup`, `num_atoms`, `density`, `lattice`, `generation_time_s`, `xyz` (for 3D viewer), and optionally `alignn_predictions` (formation_energy, bandgap, bulk_modulus, shear_modulus, supercon_tc_predicted).
 
-```python
-import requests
-
-response = requests.post(
-    "https://atomgpt.org/supercon/generate",
-    headers={
-        "Authorization": "Bearer sk-XYZ",
-        "accept": "application/json",
-        "Content-Type": "application/json",
-    },
-    json={"jid": "JVASP-1002"},
-)
-data = response.json()
-print(data)
+---
+
+### `GET /supercon/generate` — Lightweight inverse design (GET)
+
+Same as POST but via query parameters:
+
+```bash
+curl "https://atomgpt.org/supercon/generate?formula=MgB2&tc=39&relax=false&max_new_tokens=512" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "accept: application/json"
+```
+
+---
+
+### `GET /supercon/search` — Search SuperconDB by elements
+
+Search the DFT-based BCS superconductor database by element combination. Returns entries containing ALL specified elements, sorted by Tc descending.
+
+```bash
+curl "https://atomgpt.org/supercon/search?elements=Mg,B" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "accept: application/json"
+```
+
+```bash
+curl "https://atomgpt.org/supercon/search?elements=Nb" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "accept: application/json"
+```
+
+```bash
+curl "https://atomgpt.org/supercon/search?elements=La,H" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "accept: application/json"
+```
+
+| Param | Description |
+|-------|-------------|
+| `elements` | Comma-separated elements (e.g. `"Mg,B"`, `"Nb"`, `"La,H"`) |
+
+**Response** includes `count`, `elements`, and `entries` array with: `jid`, `formula`, `tc` (K), `lambda` (electron-phonon coupling), `wlog` (K), `pressure`, `stability`, `a2F_x`, `a2F_y` (Eliashberg function data for plotting).
+
+---
+
+### `POST /supercon/predict_tc` — Predict Tc from POSCAR
+
+Predict superconducting Tc and 7 other properties from any crystal structure using ALIGNN pre-trained models. Max 50 atoms.
+
+```bash
+curl -X POST "https://atomgpt.org/supercon/predict_tc" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "poscar": "MgB2\n1.0\n1.537 -2.662 0.0\n1.537 2.662 0.0\n0.0 0.0 3.515\nMg B\n1 2\nCartesian\n0.0 0.0 0.0\n1.537 -0.887 1.757\n1.537 0.887 1.757"
+  }'
 ```
 
-## AGAPI Agent
+**Response** includes `formula`, `num_atoms`, `spacegroup`, and `properties`:
+
+| Property | Unit | Description |
+|----------|------|-------------|
+| `supercon_tc` | K | Predicted superconducting Tc |
+| `formation_energy` | eV/atom | Formation energy |
+| `total_energy` | eV/atom | Total energy |
+| `bandgap_optb88` | eV | Band gap (OptB88vdW) |
+| `bandgap_mbj` | eV | Band gap (mBJ) |
+| `bulk_modulus` | GPa | Bulk modulus (Voigt) |
+| `shear_modulus` | GPa | Shear modulus (Voigt) |
+| `piezoelectric` | — | Max piezoelectric constant |
+
+---
+
+## Python Examples
+
+=== "Inverse design"
+
+    ```python
+    import requests
+
+    response = requests.post(
+        "https://atomgpt.org/supercon/generate",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={
+            "formula": "MgB2",
+            "tc": 39.0,
+            "relax": True,
+            "run_alignn": True,
+        },
+    )
+    data = response.json()
+    if data["success"]:
+        print(f"Generated: {data['formula_generated']} ({data['spacegroup']})")
+        print(f"Atoms: {data['num_atoms']}, Time: {data['generation_time_s']}s")
+        if "alignn_predictions" in data:
+            ap = data["alignn_predictions"]
+            print(f"Predicted Tc: {ap.get('supercon_tc_predicted', '?')} K")
+        print(f"POSCAR:\n{data['poscar'][:300]}")
+    ```
+
+=== "Database search"
+
+    ```python
+    import requests
+
+    response = requests.get(
+        "https://atomgpt.org/supercon/search",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+        },
+        params={"elements": "Nb"},
+    )
+    data = response.json()
+    print(f"Found {data['count']} Nb superconductors")
+    for e in data["entries"][:10]:
+        print(f"  {e['jid']:12s} {e['formula']:10s} Tc={e['tc']} K  λ={e['lambda']}")
+    ```
+
+=== "Predict Tc"
+
+    ```python
+    import requests
+
+    MGB2_POSCAR = """MgB2
+    1.0
+    1.537 -2.662 0.0
+    1.537 2.662 0.0
+    0.0 0.0 3.515
+    Mg B
+    1 2
+    Cartesian
+    0.0 0.0 0.0
+    1.537 -0.887 1.757
+    1.537 0.887 1.757"""
+
+    response = requests.post(
+        "https://atomgpt.org/supercon/predict_tc",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={"poscar": MGB2_POSCAR},
+    )
+    data = response.json()
+    if data["success"]:
+        p = data["properties"]
+        print(f"{data['formula']} ({data['spacegroup']})")
+        print(f"  Predicted Tc: {p['supercon_tc']:.2f} K")
+        print(f"  Formation energy: {p['formation_energy']:.3f} eV/atom")
+        print(f"  Band gap: {p['bandgap_optb88']:.3f} eV")
+    ```
+
+## AGAPI Agent [WIP]
 
 ```python
 from agapi.agents import AGAPIAgent
 import os
 
 agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
-response = agent.query_sync("Show supercongpt for Silicon")
+
+# Inverse design
+response = agent.query_sync("Generate a crystal structure for MgB2 with Tc=39K using SuperconGPT")
 print(response)
-```
 
-## Reference
+# Database search
+response = agent.query_sync("Search for Nb-based superconductors in SuperconDB")
+print(response)
+
+# Predict Tc
+response = agent.query_sync("Predict the superconducting Tc for JVASP-1002")
+print(response)
+```
 
-- NPJ Comp. Mat. 8, 244 (2023); J. Phys. Chem. Lett. 15, 6909 (2024)
+## References
+
+- K. Choudhary, K. Garrity, npj Comp. Mat. 8, 244 (2022) — Designing High-Tc Superconductors with BCS-Inspired Screening [:material-link: DOI](https://doi.org/10.1038/s41524-022-00933-1)
+- K. Choudhary, J. Phys. Chem. Lett. 15, 6909 (2024) — AtomGPT [:material-link: DOI](https://doi.org/10.1021/acs.jpclett.4c01126)
+- D. Wines, T. Xie, K. Choudhary, J. Phys. Chem. Lett. 14, 6630 (2023) — Inverse Design of Superconductors [:material-link: DOI](https://doi.org/10.1021/acs.jpclett.3c01260)
+- D. Wines, K. Choudhary et al., Nano Lett. 23, 969 (2023) — 2D Superconductors [:material-link: DOI](https://doi.org/10.1021/acs.nanolett.2c04420)
+- D. Wines, K. Choudhary, Materials Futures 3, 025602 (2024) — High-Pressure Hydride Superconductors [:material-link: DOI](https://doi.org/10.1088/2752-5724/ad4a94)
+- Charles Rhys Campbell, Aldo H. Romero, and Kamal Choudhary, AtomBench: A Benchmarking Framework for Generative Crystal Reconstruction Models in Conventional Superconductors [:material-link: DOI](https://arxiv.org/pdf/2510.16165)
+- [atomgptlab/atomgpt](https://github.com/atomgptlab/atomgpt)
+- [atomgptlab/alignn](https://github.com/atomgptlab/alignn)
+- [atomgptlab/atombench_inverse](https://github.com/atomgptlab/atombench_inverse)
diff --git a/docs/apps/build/heterostructure.md b/docs/apps/build/heterostructure.md
new file mode 100644
index 0000000..aebefaf
--- /dev/null
+++ b/docs/apps/build/heterostructure.md
@@ -0,0 +1,245 @@
+---
+title: Heterostructure Builder
+---
+
+# Heterostructure Builder
+
+Three-tab interface design platform: (1) Interface Generator — build heterostructure interfaces using the Zur & McGill ZSL lattice-matching algorithm via InterMat (`InterfaceCombi`), with optional ALIGNN-FF work of adhesion calculation, (2) 2D Materials — select two monolayers from JARVIS for band alignment classification (Type I/II/III) and van der Waals heterostructure generation, (3) Interface Database — search the JARVIS interface database by elements via OPTIMADE.
+
+[:material-open-in-new: Open App](https://atomgpt.org/heterostructure){ .md-button .md-button--primary }
+
+---
+
+## Overview
+
+The Heterostructure Builder combines three complementary tools for interface science. The Interface Generator accepts film/substrate structures as POSCAR or JARVIS JIDs, applies ZSL lattice matching with configurable Miller indices, slab thicknesses, tolerances, and separation, and returns the combined interface POSCAR with mismatch metrics. The 2D tab predicts heterojunction type (I, II, or III) from VBM/CBM band offsets. The database tab searches the JARVIS interface database (607 entries) via the OPTIMADE REST API.
+
+!!! info "Data Source"
+    **InterMat** — `InterfaceCombi` for ZSL lattice matching.
+    **JARVIS dft_2d** — monolayer data with work functions (φ) for band alignment.
+    **JARVIS interfacedb** — 607 pre-computed interface entries via OPTIMADE.
+    **ALIGNN-FF** — optional work of adhesion (W_ad) calculation.
+
+## Endpoints
+
+### `POST /heterostructure/generate` — Generate interface (ZSL)
+
+Build a heterostructure interface from film and substrate structures using InterfaceCombi. Input as POSCAR text or JARVIS JIDs.
+
+```bash
+curl -X POST "https://atomgpt.org/heterostructure/generate" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "poscar_film": "Si\n1.0\n5.468 0 0\n0 5.468 0\n0 0 5.468\nSi\n8\nDirect\n0 0 0\n0.5 0.5 0\n0.5 0 0.5\n0 0.5 0.5\n0.25 0.25 0.25\n0.75 0.75 0.25\n0.75 0.25 0.75\n0.25 0.75 0.75",
+    "poscar_subs": "Ge\n1.0\n5.658 0 0\n0 5.658 0\n0 0 5.658\nGe\n8\nDirect\n0 0 0\n0.5 0.5 0\n0.5 0 0.5\n0 0.5 0.5\n0.25 0.25 0.25\n0.75 0.75 0.25\n0.75 0.25 0.75\n0.25 0.75 0.75",
+    "film_indices": "0_0_1",
+    "subs_indices": "0_0_1",
+    "film_thickness": 16.0,
+    "subs_thickness": 16.0,
+    "max_area": 400.0,
+    "ltol": 0.08,
+    "separation": 2.5,
+    "vacuum_interface": 2.0,
+    "from_conventional": true,
+    "calculate_wad": false
+  }'
+```
+
+Using JARVIS JIDs instead of POSCARs:
+
+```bash
+curl -X POST "https://atomgpt.org/heterostructure/generate" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "film_ids": "JVASP-1002",
+    "subs_ids": "JVASP-1174",
+    "film_indices": "0_0_1",
+    "subs_indices": "0_0_1",
+    "max_area": 400,
+    "calculate_wad": true
+  }'
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `poscar_film` | string | — | Film POSCAR (provide this OR `film_ids`) |
+| `poscar_subs` | string | — | Substrate POSCAR (provide this OR `subs_ids`) |
+| `film_ids` | string | — | Comma-separated JARVIS JIDs for film |
+| `subs_ids` | string | — | Comma-separated JARVIS JIDs for substrate |
+| `film_indices` | string | `"0_0_1"` | Film Miller indices (h_k_l) |
+| `subs_indices` | string | `"0_0_1"` | Substrate Miller indices |
+| `film_thickness` | float | 16.0 | Film slab thickness (Å) |
+| `subs_thickness` | float | 16.0 | Substrate slab thickness (Å) |
+| `max_area` | float | 400.0 | Max supercell area (Ų) |
+| `ltol` | float | 0.08 | Length tolerance for ZSL matching |
+| `separation` | float | 2.5 | Interface separation (Å) |
+| `vacuum_interface` | float | 2.0 | Vacuum at interface (Å) |
+| `disp_intvl` | float | 0.0 | Displacement interval |
+| `max_area_ratio_tol` | float | 1.0 | Max area ratio tolerance |
+| `max_length_tol` | float | 0.03 | Max length tolerance |
+| `max_angle_tol` | float | 0.01 | Max angle tolerance |
+| `from_conventional` | bool | true | Use conventional cell for slab construction |
+| `id_tag` | string | `"jid"` | ID tag type for JID lookups |
+| `calculate_wad` | bool | false | Compute work of adhesion with ALIGNN-FF |
+
+**Response** includes `combined_poscar`, `film_poscar`, `subs_poscar`, `combined_xyz`, formulas, atom counts, `mismatch_u`, `mismatch_v`, `mismatch_angle`, and optionally `min_wad` (J/m²).
+
+---
+
+### `GET /heterostructure/monolayer-options` — List 2D monolayers
+
+```bash
+curl "https://atomgpt.org/heterostructure/monolayer-options" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "accept: application/json"
+```
+
+Returns `{"success": true, "options": [{"jid": "JVASP-664", "formula": "MoS2", "spg": "P-6m2"}, ...]}`.
+
+---
+
+### `POST /heterostructure/twod` — 2D heterostructure + band alignment
+
+Select two 2D monolayers by JID. Predicts heterojunction type (I, II, or III), band offsets (VBM/CBM), stacking type, and generates the combined interface.
+
+```bash
+curl -X POST "https://atomgpt.org/heterostructure/twod" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "jid1": "JVASP-664",
+    "jid2": "JVASP-680"
+  }'
+```
+
+**Response** includes `int_type` (I, II, or III), `stack`, `vbm_a`/`vbm_b`/`cbm_a`/`cbm_b` (eV relative to vacuum), `combined_poscar`, `combined_xyz`, `mismatch_u`/`mismatch_v`.
+
+---
+
+### `POST /heterostructure/search-db` — Search JARVIS interface database
+
+Search 607 pre-computed interface entries by elements via the JARVIS OPTIMADE REST API.
+
+```bash
+curl -X POST "https://atomgpt.org/heterostructure/search-db" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "elements": "Si-Ge"
+  }'
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `elements` | string | Dash-separated element list (e.g. `"Si-Ge"`, `"Ga-N-Al"`) |
+
+**Response** includes `count`, `rows` array with: `jid`, `formula`, `energy`, `bandgap`, `cbm`, `vbm`, `offset`.
+
+---
+
+## Python Examples
+
+=== "Generate Si/Ge interface"
+
+    ```python
+    import requests
+
+    response = requests.post(
+        "https://atomgpt.org/heterostructure/generate",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={
+            "poscar_film": open("Si.vasp").read(),
+            "poscar_subs": open("Ge.vasp").read(),
+            "film_indices": "0_0_1",
+            "subs_indices": "0_0_1",
+            "max_area": 400,
+            "separation": 2.5,
+            "calculate_wad": True,
+        },
+    )
+    data = response.json()
+    if data["success"]:
+        print(f"Interface: {data['combined_formula']} ({data['n_atoms_combined']} atoms)")
+        print(f"  Mismatch: u={data['mismatch_u']*100:.2f}%, v={data['mismatch_v']*100:.2f}%")
+        if "min_wad" in data:
+            print(f"  W_ad: {data['min_wad']:.3f} J/m²")
+        with open("POSCAR_interface", "w") as f:
+            f.write(data["combined_poscar"])
+    ```
+
+=== "2D band alignment"
+
+    ```python
+    import requests
+
+    response = requests.post(
+        "https://atomgpt.org/heterostructure/twod",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={"jid1": "JVASP-664", "jid2": "JVASP-680"},
+    )
+    data = response.json()
+    if data["success"]:
+        print(f"Type {data['int_type']} ({data['stack']} stacking)")
+        print(f"  {data['labels'][0]}: VBM={data['vbms'][0]}, CBM={data['cbms'][0]} eV")
+        print(f"  {data['labels'][1]}: VBM={data['vbms'][1]}, CBM={data['cbms'][1]} eV")
+        print(f"  Mismatch: {data['mismatch_u']*100:.2f}%")
+    ```
+
+=== "Search interface DB"
+
+    ```python
+    import requests
+
+    response = requests.post(
+        "https://atomgpt.org/heterostructure/search-db",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={"elements": "Si-Ge"},
+    )
+    data = response.json()
+    print(f"Found {data['count']} interfaces")
+    for row in data["rows"][:5]:
+        print(f"  {row['jid']:12s} {row['formula']:10s} gap={row['bandgap']} eV")
+    ```
+
+## AGAPI Agent
+
+```python
+from agapi.agents import AGAPIAgent
+import os
+
+agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
+
+# Generate interface
+response = agent.query_sync("Generate a Si/Ge heterostructure interface along (001)")
+print(response)
+
+# 2D band alignment
+response = agent.query_sync("Predict the band alignment type for MoS2/WS2 heterostructure")
+print(response)
+```
+
+## References
+
+- K. Choudhary et al., Phys. Rev. Mat. 7, 014009 (2023) [:material-link: DOI](https://doi.org/10.1103/PhysRevMaterials.7.014009)
+- K. Choudhary et al., Digital Discovery 3, 1209 (2024) — InterMat [:material-link: DOI](https://doi.org/10.1039/D4DD00031E)
+- K. Choudhary, arXiv:2004.03025 (2020) — 2D Heterostructures [:material-link: arXiv](https://arxiv.org/abs/2004.03025)
+- [atomgptlab/intermat](https://github.com/atomgptlab/intermat)
+- [atomgptlab/jarvis](https://github.com/atomgptlab/jarvis)
diff --git a/docs/apps/build/index.md b/docs/apps/build/index.md
new file mode 100644
index 0000000..f5b59e4
--- /dev/null
+++ b/docs/apps/build/index.md
@@ -0,0 +1,6 @@
+---
+title: Index
+---
+
+# Build Apps
+See sidebar for individual apps.
diff --git a/docs/apps/build/structure-visualizer.md b/docs/apps/build/structure-visualizer.md
new file mode 100644
index 0000000..711ab76
--- /dev/null
+++ b/docs/apps/build/structure-visualizer.md
@@ -0,0 +1,315 @@
+---
+title: Structure Visualizer
+---
+
+# Structure Visualizer
+
+Interactive 3D crystal structure viewer and manipulator. Load structures from POSCAR, CIF, XYZ, or PDB format. Build supercells, create surfaces with vacuum, introduce vacancies and substitutions, convert between primitive and conventional cells, and generate XRD patterns. All transformations return updated POSCAR, XYZ (for 3Dmol rendering), and structural info (formula, space group, volume, density).
+
+[:material-open-in-new: Open App](https://atomgpt.org/structure_visualizer){ .md-button .md-button--primary }
+
+---
+
+## Overview
+
+The Structure Visualizer provides a full suite of crystal structure manipulation tools in the browser with a 3Dmol.js interactive viewer. Each operation takes a POSCAR input, applies the transformation server-side using jarvis-tools, and returns the modified structure with updated metadata. Max 500 atoms per structure. Supported input formats: POSCAR, CIF, XYZ, PDB.
+
+!!! info "Data Source"
+    **User input** — paste or upload crystal structures.
+    **jarvis-tools** — `jarvis.core.atoms`, `jarvis.analysis.defects.surface`, `jarvis.analysis.diffraction.xrd`.
+
+## Endpoints
+
+### `POST /structure_visualizer/load` — Load and parse structure
+
+Load a structure from POSCAR, CIF, XYZ, or PDB format. Returns POSCAR, XYZ (for 3D viewer), and structural info.
+
+```bash
+curl -X POST "https://atomgpt.org/structure_visualizer/load" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "structure": "Al FCC\n1.0\n4.05 0.0 0.0\n0.0 4.05 0.0\n0.0 0.0 4.05\nAl\n4\ndirect\n0.0 0.0 0.0\n0.5 0.5 0.0\n0.5 0.0 0.5\n0.0 0.5 0.5",
+    "format": "poscar"
+  }'
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `structure` | string | required | Structure file content |
+| `format` | string | `"poscar"` | `"poscar"`, `"cif"`, `"xyz"`, or `"pdb"` |
+
+**Response** (same for all manipulation endpoints): `poscar`, `xyz`, `info` (formula, num_atoms, spacegroup, volume, density, elements, coords).
+
+---
+
+### `POST /structure_visualizer/supercell` — Build supercell
+
+```bash
+curl -X POST "https://atomgpt.org/structure_visualizer/supercell" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "poscar": "Al FCC\n1.0\n4.05 0.0 0.0\n0.0 4.05 0.0\n0.0 0.0 4.05\nAl\n4\ndirect\n0.0 0.0 0.0\n0.5 0.5 0.0\n0.5 0.0 0.5\n0.0 0.5 0.5",
+    "dimensions": [2, 2, 2]
+  }'
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `poscar` | string | Input POSCAR |
+| `dimensions` | list[int] | Supercell dimensions [nx, ny, nz], each 1–5 |
+
+---
+
+### `POST /structure_visualizer/surface` — Create surface slab
+
+```bash
+curl -X POST "https://atomgpt.org/structure_visualizer/surface" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "poscar": "Al FCC\n1.0\n4.05 0.0 0.0\n0.0 4.05 0.0\n0.0 0.0 4.05\nAl\n4\ndirect\n0.0 0.0 0.0\n0.5 0.5 0.0\n0.5 0.0 0.5\n0.0 0.5 0.5",
+    "miller_indices": [1, 1, 0],
+    "vacuum": 15.0
+  }'
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `poscar` | string | required | Input POSCAR |
+| `miller_indices` | list[int] | required | Miller indices [h, k, l] |
+| `vacuum` | float | 15.0 | Vacuum thickness (Å) |
+
+---
+
+### `POST /structure_visualizer/vacancy` — Create vacancy defect
+
+```bash
+curl -X POST "https://atomgpt.org/structure_visualizer/vacancy" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "poscar": "Al FCC\n1.0\n4.05 0.0 0.0\n0.0 4.05 0.0\n0.0 0.0 4.05\nAl\n4\ndirect\n0.0 0.0 0.0\n0.5 0.5 0.0\n0.5 0.0 0.5\n0.0 0.5 0.5",
+    "atom_index": 0
+  }'
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `poscar` | string | Input POSCAR |
+| `atom_index` | int | 0-indexed atom position to remove |
+
+---
+
+### `POST /structure_visualizer/substitution` — Substitute atom
+
+```bash
+curl -X POST "https://atomgpt.org/structure_visualizer/substitution" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "poscar": "Al FCC\n1.0\n4.05 0.0 0.0\n0.0 4.05 0.0\n0.0 0.0 4.05\nAl\n4\ndirect\n0.0 0.0 0.0\n0.5 0.5 0.0\n0.5 0.0 0.5\n0.0 0.5 0.5",
+    "atom_index": 0,
+    "new_element": "Cu"
+  }'
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `poscar` | string | Input POSCAR |
+| `atom_index` | int | 0-indexed atom position to substitute |
+| `new_element` | string | New element symbol (e.g. `"Cu"`, `"Fe"`, `"N"`) |
+
+---
+
+### `POST /structure_visualizer/to_primitive` — Convert to primitive cell
+
+```bash
+curl -X POST "https://atomgpt.org/structure_visualizer/to_primitive" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "poscar": "Si Diamond\n1.0\n5.43 0.0 0.0\n0.0 5.43 0.0\n0.0 0.0 5.43\nSi\n8\ndirect\n0.0 0.0 0.0\n0.25 0.25 0.25\n0.5 0.5 0.0\n0.75 0.75 0.25\n0.5 0.0 0.5\n0.75 0.25 0.75\n0.0 0.5 0.5\n0.25 0.75 0.75"
+  }'
+```
+
+---
+
+### `POST /structure_visualizer/to_conventional` — Convert to conventional cell
+
+```bash
+curl -X POST "https://atomgpt.org/structure_visualizer/to_conventional" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "poscar": "Si\n1.0\n0 2.734 2.734\n2.734 0 2.734\n2.734 2.734 0\nSi\n2\ndirect\n0 0 0\n0.25 0.25 0.25"
+  }'
+```
+
+---
+
+### `POST /structure_visualizer/xrd` — Generate XRD pattern
+
+```bash
+curl -X POST "https://atomgpt.org/structure_visualizer/xrd" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "poscar": "Si\n1.0\n0 2.734 2.734\n2.734 0 2.734\n2.734 2.734 0\nSi\n2\ndirect\n0 0 0\n0.25 0.25 0.25"
+  }'
+```
+
+Returns `num_peaks`, `top_peak` (2θ of strongest peak), `theta` (array), `intensities` (array).
+
+---
+
+## Python Examples
+
+=== "Load and visualize"
+
+    ```python
+    import requests
+
+    AL_POSCAR = """Al FCC
+    1.0
+    4.05 0.0 0.0
+    0.0 4.05 0.0
+    0.0 0.0 4.05
+    Al
+    4
+    direct
+    0.0 0.0 0.0
+    0.5 0.5 0.0
+    0.5 0.0 0.5
+    0.0 0.5 0.5"""
+
+    response = requests.post(
+        "https://atomgpt.org/structure_visualizer/load",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={"structure": AL_POSCAR, "format": "poscar"},
+    )
+    data = response.json()
+    info = data["info"]
+    print(f"{info['formula']} — {info['num_atoms']} atoms")
+    print(f"  Spacegroup: {info['spacegroup']}")
+    print(f"  Volume: {info['volume']:.2f} ų")
+    print(f"  Density: {info['density']:.2f} g/cm³")
+    ```
+
+=== "Build supercell"
+
+    ```python
+    import requests
+
+    response = requests.post(
+        "https://atomgpt.org/structure_visualizer/supercell",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={
+            "poscar": open("POSCAR").read(),
+            "dimensions": [2, 2, 1],
+        },
+    )
+    data = response.json()
+    print(f"Supercell: {data['info']['num_atoms']} atoms")
+    with open("POSCAR_supercell", "w") as f:
+        f.write(data["poscar"])
+    ```
+
+=== "Create surface + vacancy"
+
+    ```python
+    import requests
+
+    HEADERS = {
+        "Authorization": "Bearer sk-XYZ",
+        "accept": "application/json",
+        "Content-Type": "application/json",
+    }
+    poscar = open("POSCAR").read()
+
+    # Create (110) surface
+    resp = requests.post(
+        "https://atomgpt.org/structure_visualizer/surface",
+        headers=HEADERS,
+        json={"poscar": poscar, "miller_indices": [1, 1, 0], "vacuum": 15.0},
+    )
+    surface_poscar = resp.json()["poscar"]
+    print(f"Surface: {resp.json()['info']['num_atoms']} atoms")
+
+    # Create vacancy at atom 0
+    resp = requests.post(
+        "https://atomgpt.org/structure_visualizer/vacancy",
+        headers=HEADERS,
+        json={"poscar": surface_poscar, "atom_index": 0},
+    )
+    print(f"With vacancy: {resp.json()['info']['num_atoms']} atoms")
+    with open("POSCAR_surface_vacancy", "w") as f:
+        f.write(resp.json()["poscar"])
+    ```
+
+=== "XRD pattern"
+
+    ```python
+    import requests
+    import matplotlib.pyplot as plt
+
+    response = requests.post(
+        "https://atomgpt.org/structure_visualizer/xrd",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={"poscar": open("POSCAR").read()},
+    )
+    data = response.json()
+    print(f"Peaks: {data['num_peaks']}, Top at 2θ={data['top_peak']:.2f}°")
+
+    plt.figure(figsize=(8, 4))
+    plt.stem(data["theta"], data["intensities"], linefmt="b-", markerfmt="bo", basefmt="k-")
+    plt.xlabel("2θ (degrees)")
+    plt.ylabel("Intensity")
+    plt.title("Powder XRD Pattern")
+    plt.tight_layout()
+    plt.savefig("xrd_pattern.png")
+    ```
+
+## AGAPI Agent
+
+```python
+from agapi.agents import AGAPIAgent
+import os
+
+agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
+
+# Load structure
+response = agent.query_sync("Visualize the crystal structure of Al FCC")
+print(response)
+
+# Build supercell
+response = agent.query_sync("Create a 2x2x2 supercell of Si")
+print(response)
+```
+
+## References
+
+- K. Choudhary, Comp. Mat. Sci. 259, 114063 (2025) [:material-link: DOI](https://doi.org/10.1016/j.commatsci.2025.114063)
+- K. Choudhary et al., npj Comp. Mat. 6, 173 (2020) [:material-link: DOI](https://doi.org/10.1038/s41524-020-00440-1)
+- [atomgptlab/jarvis](https://github.com/atomgptlab/jarvis)
diff --git a/docs/apps/build/workflow.md b/docs/apps/build/workflow.md
new file mode 100644
index 0000000..3001972
--- /dev/null
+++ b/docs/apps/build/workflow.md
@@ -0,0 +1,238 @@
+---
+title: Workflow Builder
+---
+
+# Workflow Builder
+
+Visual pipeline builder for the JARVIS computational materials science ecosystem. Drag-and-drop 32 blocks across 9 categories (input, transform, DFT, force field/MLFF, GNN/ML, tight binding, quantum, analysis, output) to build computational pipelines. Choose from 8 pre-built templates or create custom workflows. Auto-generates ready-to-run Python scripts using jarvis-tools, ALIGNN, AtomGPT, SlakoNet, and Qiskit.
+
+[:material-open-in-new: Open App](https://atomgpt.org/workflow){ .md-button .md-button--primary }
+
+---
+
+## Overview
+
+The Workflow Builder is a code generator, not a compute engine — it produces Python scripts that you run locally or on a cluster. The three-panel UI has a block palette (left), pipeline canvas (center), and live script preview (right). Each block maps to a Python code template that is composed into a complete script with proper variable wiring between blocks.
+
+!!! info "How It Works"
+    **No computation happens server-side.** The app generates Python scripts from your pipeline definition. You run the generated `.py` file in your own environment with the required packages installed.
+
+## Block Categories
+
+| Category | Blocks | Description |
+|----------|--------|-------------|
+| **Input** | `jarvis_id`, `poscar_input`, `formula_input` | Load structures from JARVIS, POSCAR text, or formula |
+| **Transform** | `supercell`, `vacancy`, `surface`, `heterostructure` | Structure manipulation |
+| **DFT** | `vasp_relax`, `vasp_bands`, `vasp_optics`, `vasp_elastic`, `vasp_phonon`, `vasp_factory`, `qe_relax` | VASP and QE job generation |
+| **Force Field** | `alignn_ff_opt`, `alignn_ff_md`, `alignn_ff_phonon`, `lammps_ff`, `chipsff_bench` | ML and classical force fields |
+| **GNN / ML** | `alignn_predict`, `atomgpt_predict`, `atomgpt_generate`, `cfid_descriptors` | Property prediction and inverse design |
+| **Tight Binding** | `slakonet_bands`, `wannier_tb`, `chipstb_bench` | TB band structure methods |
+| **Quantum** | `vqe_electron` | VQE electronic structure via Qiskit |
+| **Analysis** | `xrd_analysis`, `rdf_analysis`, `spacegroup_analysis` | Structural characterization |
+| **Output** | `save_poscar`, `leaderboard_submit` | Export and benchmarking |
+
+## Pre-built Templates
+
+| Template | Pipeline |
+|----------|----------|
+| DFT Full | JARVIS ID → VASP JobFactory (relax + bands + optics + elastic) |
+| MLFF | JARVIS ID → ALIGNN-FF optimize → MD → phonons |
+| GNN Screen | JARVIS ID → ALIGNN predict (formation energy, band gap, bulk modulus) |
+| Surface Study | JARVIS ID → surface slab → spacegroup analysis → XRD |
+| Defect Study | JARVIS ID → vacancies → ALIGNN-FF optimize |
+| TB Bands | JARVIS ID → SlakoNet bands → Wannier TB bands |
+| Quantum VQE | VQE electronic at X-point for Al |
+| Inverse Design | AtomGPT generate → ALIGNN validate → save POSCAR |
+
+## Endpoints
+
+### `GET /workflow/blocks` — List all available blocks
+
+Returns the full block definition catalog with parameters, categories, and I/O types.
+
+```bash
+curl "https://atomgpt.org/workflow/blocks" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "accept: application/json"
+```
+
+---
+
+### `GET /workflow/templates` — List pre-built templates
+
+Returns 8 template definitions with block sequences and default parameters.
+
+```bash
+curl "https://atomgpt.org/workflow/templates" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "accept: application/json"
+```
+
+---
+
+### `POST /workflow/generate` — Generate Python script
+
+Submit a pipeline definition (list of blocks with parameters) and receive a ready-to-run Python script.
+
+```bash
+curl -X POST "https://atomgpt.org/workflow/generate" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "name": "si_screening",
+    "blocks": [
+      {
+        "type": "jarvis_id",
+        "params": {"jid": "JVASP-1002", "dataset": "dft_3d"}
+      },
+      {
+        "type": "alignn_predict",
+        "params": {"model_name": "formation_energy_peratom"}
+      },
+      {
+        "type": "alignn_predict",
+        "params": {"model_name": "optb88vdw_bandgap"}
+      },
+      {
+        "type": "alignn_ff_opt",
+        "params": {"model": "alignnff_wt10", "fmax": "0.05", "steps": "200"}
+      }
+    ]
+  }'
+```
+
+MLFF workflow example:
+
+```bash
+curl -X POST "https://atomgpt.org/workflow/generate" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "name": "mlff_workflow",
+    "blocks": [
+      {"type": "jarvis_id", "params": {"jid": "JVASP-1002", "dataset": "dft_3d"}},
+      {"type": "alignn_ff_opt", "params": {"model": "alignnff_wt10", "fmax": "0.05", "steps": "200"}},
+      {"type": "alignn_ff_md", "params": {"model": "alignnff_wt10", "temp": "300", "timestep": "1", "nsteps": "1000"}},
+      {"type": "alignn_ff_phonon", "params": {"model": "alignnff_wt10", "dim": "2,2,2"}}
+    ]
+  }'
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | Workflow name (used as script filename) |
+| `blocks` | list | Ordered list of pipeline blocks |
+| `blocks[].type` | string | Block type key (e.g. `"jarvis_id"`, `"alignn_predict"`) |
+| `blocks[].params` | dict | Block-specific parameters (see block definitions) |
+| `blocks[].id` | string | Optional custom block ID |
+
+**Response:**
+
+| Field | Description |
+|-------|-------------|
+| `script` | Generated Python script as string |
+| `name` | Workflow name |
+| `n_blocks` | Number of blocks in pipeline |
+| `block_types` | Ordered list of block type names |
+
+---
+
+## Python Examples
+
+=== "Generate GNN screening script"
+
+    ```python
+    import requests
+
+    response = requests.post(
+        "https://atomgpt.org/workflow/generate",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={
+            "name": "gnn_screen_si",
+            "blocks": [
+                {"type": "jarvis_id", "params": {"jid": "JVASP-1002", "dataset": "dft_3d"}},
+                {"type": "alignn_predict", "params": {"model_name": "formation_energy_peratom"}},
+                {"type": "alignn_predict", "params": {"model_name": "optb88vdw_bandgap"}},
+                {"type": "alignn_predict", "params": {"model_name": "bulk_modulus_kv"}},
+            ],
+        },
+    )
+    data = response.json()
+    print(f"Generated {data['n_blocks']}-block script")
+    print(f"Pipeline: {' → '.join(data['block_types'])}")
+
+    with open(f"{data['name']}.py", "w") as f:
+        f.write(data["script"])
+    print(f"Saved: {data['name']}.py")
+    ```
+
+=== "DFT full pipeline script"
+
+    ```python
+    import requests
+
+    response = requests.post(
+        "https://atomgpt.org/workflow/generate",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={
+            "name": "dft_full_pipeline",
+            "blocks": [
+                {"type": "jarvis_id", "params": {"jid": "JVASP-1002"}},
+                {"type": "vasp_factory", "params": {
+                    "steps": "ENCUT,KPLEN,RELAX,BANDSTRUCT,OPTICS,ELASTIC",
+                    "functional": "optb88vdw",
+                }},
+            ],
+        },
+    )
+    data = response.json()
+    with open("dft_full_pipeline.py", "w") as f:
+        f.write(data["script"])
+    ```
+
+=== "List all blocks"
+
+    ```python
+    import requests
+
+    response = requests.get(
+        "https://atomgpt.org/workflow/blocks",
+        headers={"Authorization": "Bearer sk-XYZ"},
+    )
+    blocks = response.json()["blocks"]
+    for cat in ["input", "transform", "dft", "ff", "ml", "tb", "quantum", "analysis", "output"]:
+        items = [k for k, v in blocks.items() if v["category"] == cat]
+        if items:
+            print(f"\n{cat.upper()}: {len(items)} blocks")
+            for k in items:
+                print(f"  {k:25s} {blocks[k]['label']}")
+    ```
+
+## AGAPI Agent [WIP]
+
+```python
+from agapi.agents import AGAPIAgent
+import os
+
+agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
+
+# Generate MLFF workflow
+response = agent.query_sync("Generate an MLFF workflow script for Si using ALIGNN-FF")
+print(response)
+```
+
+## References
+
+- K. Choudhary et al., npj Comp. Mat. 6, 173 (2020) — JARVIS [:material-link: DOI](https://doi.org/10.1038/s41524-020-00440-1)
+- K. Choudhary, Comp. Mat. Sci. 259, 114063 (2025) [:material-link: DOI](https://doi.org/10.1016/j.commatsci.2025.114063)
+- [atomgptlab/alignn](https://github.com/atomgptlab/alignn) | [atomgptlab/atomgpt](https://github.com/atomgptlab/atomgpt) | [atomgptlab/slakonet](https://github.com/atomgptlab/slakonet)
diff --git a/docs/apps/characterize/microscopy.md b/docs/apps/characterize/microscopy.md
index d79d77d..57c0389 100644
--- a/docs/apps/characterize/microscopy.md
+++ b/docs/apps/characterize/microscopy.md
@@ -1,10 +1,10 @@
 ---
-title: MicroscopyGPT
+title: Microscopy Suite
 ---
 
-# MicroscopyGPT
+# Microscopy Suite
 
-Microscopy Suite with 3 tabs: (1) STEM Analyzer — proxy to MicroscopyGPT service (port 7000) for atom column detection and classification, (2) STEM Generator — simulate STEM images from crystal structures, (3) STM Image generator.
+Three-tab microscopy platform: (1) STEM Analyzer — AI-powered structure prediction from STEM/TEM images using MicroscopyGPT + SAM3 atomic column segmentation, (2) STEM Generator — simulate STEM images from crystal structures using STEMConv, (3) STM Viewer — browse pre-computed scanning tunneling microscopy images from JARVIS-DFT.
 
 [:material-open-in-new: Open App](https://atomgpt.org/microscopy){ .md-button .md-button--primary }
 
@@ -12,54 +12,289 @@ Microscopy Suite with 3 tabs: (1) STEM Analyzer — proxy to MicroscopyGPT servi
 
 ## Overview
 
-Microscopy Suite with 3 tabs: (1) STEM Analyzer — proxy to MicroscopyGPT service (port 7000) for atom column detection and classification, (2) STEM Generator — simulate STEM images from crystal structures, (3) STM Image generator.
+The Microscopy Suite bridges experimental imaging with computational materials science. Upload a STEM/TEM image and MicroscopyGPT predicts the underlying crystal structure (POSCAR). Detect atomic columns with SAM3 segmentation. Simulate what STEM images look like for any crystal structure. Browse 5K+ pre-computed STM images from the JARVIS-DFT database.
 
 !!! info "Data Source"
-    **MicroscopyGPT model + jarvis.io.stm**
+    **MicroscopyGPT** —fine-tuned model (vLLM served).
+    **SAM3** — Segment Anything Model for atomic dots detection.
+    **STEMConv** — Convolution approximation for STEM image simulation.
+    **JARVIS-DFT STM** — Pre-computed Tersoff-Hamann STM images from NIST/JARVIS-DFT.
 
 ## Endpoints
 
-- `GET /microscopy`
-- `GET /microscopy/health`
-- `POST /microscopy/predict`
-- `POST /microscopy/segment`
-- `POST /microscopy/stem_generate`
-- `POST /microscopy/stm_image`
+### `POST /microscopy/predict` — Predict structure from STEM image
 
-**Request Models:** —
+Upload a STEM/TEM image + chemical formula. MicroscopyGPT generates the crystal structure (lattice parameters, atomic positions). Returns POSCAR and 3D viewer data.
 
-!!! note "Authentication"
-    All POST endpoints require `Authorization: Bearer YOUR_TOKEN`.
+```bash
+curl -X POST "https://atomgpt.org/microscopy/predict" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -F "image=@stem_image.png" \
+  -F "formula=MoS2" \
+  -F "temperature=0.0" \
+  -F "do_sample=false" \
+  -F "top_p=0.9"
+```
 
-## API Example
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `image` | file | required | STEM/TEM image (PNG, JPG) |
+| `formula` | string | required | Chemical formula (e.g. `"MoS2"`, `"GaN"`, `"Si"`) |
+| `temperature` | float | 0.0 | Generation temperature (0 = deterministic) |
+| `do_sample` | bool | false | Enable sampling |
+| `top_p` | float | 0.9 | Nucleus sampling threshold |
 
-```python
-import requests
-
-response = requests.post(
-    "https://atomgpt.org/microscopy/predict",
-    headers={
-        "Authorization": "Bearer sk-XYZ",
-        "accept": "application/json",
-        "Content-Type": "application/json",
-    },
-    json={"jid": "JVASP-1002"},
-)
-data = response.json()
-print(data)
+**Response** includes `poscar`, `raw_output`, `backend` (`vllm_qwen2vl` ), and `atoms_info` (num_atoms, elements, volume, lattice_abc, lattice_angles).
+
+---
+
+### `POST /microscopy/segment` — Detect atomic columns (JSON)
+
+Upload a STEM image and detect atomic column positions using SAM3 segmentation. Returns bounding boxes, centers, and scores.
+
+```bash
+curl -X POST "https://atomgpt.org/microscopy/segment" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -F "image=@stem_image.png" \
+  -F "prompt=dots" \
+  -F "max_detections=200" \
+  -F "score_threshold=0.3"
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `image` | file | required | STEM/TEM image |
+| `prompt` | string | `"dots"` | Detection prompt (`"dots"`, `"atoms"`, `"circles"`) |
+| `max_detections` | int | 200 | Maximum detections |
+| `score_threshold` | float | 0.3 | Minimum confidence score |
+
+**Response** includes `num_detections`, `centers` (x,y pairs), `boxes`, `scores`, `lattice_stats` (avg_nearest_distance), `image_size`.
+
+---
+
+### `POST /microscopy/segment_visualize` — Detect atoms (PNG overlay)
+
+Same parameters as `/segment` but returns a PNG image with detection overlay drawn on the original image.
+
+```bash
+curl -X POST "https://atomgpt.org/microscopy/segment_visualize" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -F "image=@stem_image.png" \
+  -F "prompt=dots" \
+  -F "score_threshold=0.5" \
+  --output segmented.png
+```
+
+Returns `image/png` with bounding boxes and centers drawn.
+
+---
+
+### `POST /microscopy/stem_generate` — Simulate STEM image from POSCAR
+
+Generate a simulated STEM image from a crystal structure using STEMConv convolution approximation.
+
+```bash
+curl -X POST "https://atomgpt.org/microscopy/stem_generate" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -F "poscar_text=System
+1.0
+1.232 -2.134 0.0
+1.232 2.134 0.0
+0.0 0.0 30.803
+C
+2
+direct
+0.0 0.0 0.0633
+0.3333 0.6667 0.0633" \
+  -F "output_size=256" \
+  -F "power_factor=1.7" \
+  -F "px_scale=0.2" \
+  -F "surface_layers=1" \
+  -F "miller_index=0_0_1"
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `poscar_text` | string | required | VASP POSCAR structure |
+| `output_size` | int | 256 | Image size in pixels (128, 256, 512) |
+| `power_factor` | float | 1.7 | Contrast power factor |
+| `px_scale` | float | 0.2 | Pixel scale (Å/pixel) |
+| `surface_layers` | int | 1 | Number of surface layers |
+| `miller_index` | string | `"0_0_1"` | Miller indices as `h_k_l` |
+
+**Response** includes `image_base64` (PNG), `miller_index`, `output_size`, `num_atoms`, `formula`.
+
+---
+
+### `POST /microscopy/stm_image` — Pre-computed STM from JARVIS-DFT
+
+Fetch and render Tersoff-Hamann STM images from the JARVIS-DFT STM database hosted at NIST.
+
+```bash
+curl -X POST "https://atomgpt.org/microscopy/stm_image" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -F "jid=JVASP-667" \
+  -F "bias_type=Positive" \
+  -F "stm_type=Constant height" \
+  -F "min_size=20" \
+  -F "ext=0.15"
 ```
 
-## AGAPI Agent
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `jid` | string | required | JARVIS ID (e.g. `"JVASP-667"`) |
+| `bias_type` | string | `"Positive"` | `"Positive"` or `"Negative"` |
+| `stm_type` | string | `"Constant height"` | `"Constant height"` or `"Constant current"` |
+| `min_size` | float | 20.0 | Minimum image size (Å) |
+| `ext` | float | 0.15 | Extension parameter for constant current mode |
+| `zcut` | float | (auto) | Optional z-axis cutoff |
+
+**Response** includes `image_base64` (PNG), `jid`, `bias_type`, `stm_type`, `processing_time`.
+
+---
+
+### `GET /microscopy/health` — Service health check
+
+```bash
+curl "https://atomgpt.org/microscopy/health" \
+  -H "Authorization: Bearer sk-XYZ"
+```
+
+Returns status of the MicroscopyGPT backend service and vLLM availability.
+
+---
+
+## Python Examples
+
+=== "Predict structure"
+
+    ```python
+    import requests
+
+    with open("stem_image.png", "rb") as f:
+        response = requests.post(
+            "https://atomgpt.org/microscopy/predict",
+            headers={
+                "Authorization": "Bearer sk-XYZ",
+                "accept": "application/json",
+            },
+            files={"image": ("stem.png", f, "image/png")},
+            data={"formula": "MoS2", "temperature": "0.0"},
+        )
+    data = response.json()
+    if data["success"]:
+        print(f"Atoms: {data['atoms_info']['num_atoms']}")
+        print(f"Elements: {data['atoms_info']['elements']}")
+        print(f"POSCAR:\n{data['poscar'][:300]}")
+    ```
+
+=== "Segment atoms"
+
+    ```python
+    import requests
+
+    with open("stem_image.png", "rb") as f:
+        response = requests.post(
+            "https://atomgpt.org/microscopy/segment",
+            headers={
+                "Authorization": "Bearer sk-XYZ",
+                "accept": "application/json",
+            },
+            files={"image": ("stem.png", f, "image/png")},
+            data={"prompt": "dots", "score_threshold": "0.3"},
+        )
+    data = response.json()
+    print(f"Detected {data['num_detections']} atoms")
+    for c in data["centers"][:5]:
+        print(f"  ({c[0]:.1f}, {c[1]:.1f})")
+    ```
+
+=== "Generate STEM"
+
+    ```python
+    import requests
+
+    GRAPHENE = """System
+    1.0
+    1.232 -2.134 0.0
+    1.232 2.134 0.0
+    0.0 0.0 30.803
+    C
+    2
+    direct
+    0.0 0.0 0.0633
+    0.3333 0.6667 0.0633"""
+
+    response = requests.post(
+        "https://atomgpt.org/microscopy/stem_generate",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+        },
+        data={
+            "poscar_text": GRAPHENE,
+            "output_size": "256",
+            "miller_index": "0_0_1",
+        },
+    )
+    data = response.json()
+    if data["success"]:
+        import base64
+        with open("stem_sim.png", "wb") as f:
+            f.write(base64.b64decode(data["image_base64"]))
+        print(f"Saved: {data['formula']} [{data['miller_index']}]")
+    ```
+
+=== "STM image"
+
+    ```python
+    import requests
+
+    response = requests.post(
+        "https://atomgpt.org/microscopy/stm_image",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+        },
+        data={
+            "jid": "JVASP-667",
+            "bias_type": "Positive",
+            "stm_type": "Constant height",
+        },
+    )
+    data = response.json()
+    if data["success"]:
+        import base64
+        with open("stm.png", "wb") as f:
+            f.write(base64.b64decode(data["image_base64"]))
+        print(f"STM for {data['jid']} ({data['processing_time']}s)")
+    ```
+
+## AGAPI Agent [WIP]
 
 ```python
 from agapi.agents import AGAPIAgent
 import os
 
 agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
-response = agent.query_sync("Show microscopygpt for Silicon")
+
+# Analyze STEM image
+response = agent.query_sync("Analyze this STEM image of GaN and predict the structure")
+print(response)
+
+# Generate STEM simulation
+response = agent.query_sync("Simulate a STEM image of graphene along [001]")
+print(response)
+
+# STM image
+response = agent.query_sync("Show the STM image for JVASP-667 with positive bias")
 print(response)
 ```
 
-## Reference
+## References
 
-- J. Chem. Inf. Model 63, 1708 (2023); J. Phys. Chem. Lett. 16, 7028 (2025)
+- J. Phys. Chem. Lett. 16, 7028 (2025) — MicroscopyGPT [:material-link: DOI](https://doi.org/10.1021/acs.jpclett.5c01257)
+- J. Chem. Inf. Model 63, 1708 (2023) — AtomVision [:material-link: DOI](https://doi.org/10.1021/acs.jcim.2c01533)
+- Sci. Data 8, 57 (2021) — JARVIS STM Database
+- [atomgptlab/atomvision](https://github.com/atomgptlab/atomvision)
+- [atomgptlab/atomgpt](https://github.com/atomgptlab/atomgpt)
diff --git a/docs/apps/characterize/raman.md b/docs/apps/characterize/raman.md
index 0c52e20..d61551b 100644
--- a/docs/apps/characterize/raman.md
+++ b/docs/apps/characterize/raman.md
@@ -1,10 +1,10 @@
 ---
-title: Raman Matching
+title: Raman Suite
 ---
 
-# Raman Matching
+# Raman Suite
 
-Raman spectrum matching against JARVIS ramandb (~5K materials). User provides freq_cm vs raman_activity data + optional formula. Cosine similarity matching to find best-fit materials.
+Three-tab Raman analysis platform: (1) spectrum matching against JARVIS ramandb (~5K materials), (2) RamanGPT AI-powered structure prediction from Raman peaks, and (3) ALIGNN-based Raman spectrum prediction from crystal structures.
 
 [:material-open-in-new: Open App](https://atomgpt.org/raman){ .md-button .md-button--primary }
 
@@ -12,51 +12,271 @@ Raman spectrum matching against JARVIS ramandb (~5K materials). User provides fr
 
 ## Overview
 
-Raman spectrum matching against JARVIS ramandb (~5K materials). User provides freq_cm vs raman_activity data + optional formula. Cosine similarity matching to find best-fit materials.
+The Raman Suite provides a complete workflow for Raman spectroscopy in materials science. Match experimental spectra to known materials via cosine similarity, predict crystal structures from Raman peaks using RamanGPT, or predict Raman spectra from POSCAR structures using ALIGNN (`jv_raman_alignn`). The ramandb contains ~5K materials with DFT-computed Raman tensors, cross-referenced with JARVIS-DFT JVASP IDs.
 
 !!! info "Data Source"
-    **ramandb (~5K entries)**
+    **ramandb** (~5K entries with DFT Raman tensors).
+    **RamanGPT** model (`knc6/ramangpt_dft_model`) for AI structure prediction.
+    **ALIGNN** (`jv_raman_alignn`) for ML Raman spectrum prediction.
 
 ## Endpoints
 
-- `GET /raman`
-- `POST /raman/lookup`
-- `POST /raman/match`
+### `POST /raman/match` — Match spectrum against ramandb
 
-**Request Models:** `RamanMatchRequest`, `RamanLookupRequest`
+Gaussian-broadens user spectrum and computes cosine similarity against all entries in ramandb. Optional formula filter narrows candidates.
 
-!!! note "Authentication"
-    All POST endpoints require `Authorization: Bearer YOUR_TOKEN`.
+```bash
+curl -X POST "https://atomgpt.org/raman/match" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "frequencies": [135.2, 196.7, 221.3, 257.0, 418.3, 594.7, 650.1, 701.6, 705.6],
+    "activities": [0.024, 0.006, 0.013, 0.091, 0.083, 0.340, 0.001, 1.000, 0.137],
+    "formula": "SrTeO3",
+    "sigma": 8.0,
+    "top_n": 10,
+    "freq_min": 0,
+    "freq_max": 1200
+  }'
+```
 
-## API Example
+Match without formula filter (search entire database):
 
-```python
-import requests
-
-response = requests.post(
-    "https://atomgpt.org/raman/lookup",
-    headers={
-        "Authorization": "Bearer sk-XYZ",
-        "accept": "application/json",
-        "Content-Type": "application/json",
-    },
-    json={"jid": "JVASP-1002"},
-)
-data = response.json()
-print(data)
+```bash
+curl -X POST "https://atomgpt.org/raman/match" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "frequencies": [520, 302, 960],
+    "activities": [1.0, 0.02, 0.06],
+    "formula": "",
+    "sigma": 8.0,
+    "top_n": 5
+  }'
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `frequencies` | list[float] | required | Raman shift values (cm⁻¹) |
+| `activities` | list[float] | required | Raman activity/intensity values |
+| `formula` | string | `""` | Optional formula or element filter (e.g. `"Si"`, `"SrTeO3"`, `"Te,O"`) |
+| `sigma` | float | 8.0 | Gaussian broadening width (cm⁻¹) |
+| `top_n` | int | 10 | Number of top matches to return |
+| `freq_min` | float | 0 | Minimum frequency for matching grid |
+| `freq_max` | float | 1200 | Maximum frequency for matching grid |
+
+**Response** includes `grid` (500-point x-axis), `user_spectrum` (broadened), and `matches` array with `id`, `formula`, `elements`, `similarity`, `n_active_modes`, `active_freqs`, `active_activities`, and `spectrum` (broadened reference).
+
+---
+
+### `POST /raman/lookup` — Look up a material's Raman spectrum by ID
+
+```bash
+curl -X POST "https://atomgpt.org/raman/lookup" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "material_id": "JVASP-1002"
+  }'
 ```
 
-## AGAPI Agent
+Returns `freq_cm`, `raman_activity`, `formula`, and `elements` for the given material.
+
+---
+
+### `POST /raman/ramangpt` — AI structure prediction from Raman peaks
+
+Given a chemical formula and Raman peak data, RamanGPT generates a crystal structure (POSCAR) that would produce the observed spectrum.
+
+```bash
+curl -X POST "https://atomgpt.org/raman/ramangpt" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "formula": "SrTeO3",
+    "raman_data": "135.2  0.024\n196.7  0.006\n221.3  0.013\n257.0  0.091\n418.3  0.083\n594.7  0.340\n701.6  1.000",
+    "max_new_tokens": 512
+  }'
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `formula` | string | required | Chemical formula |
+| `raman_data` | string | required | Frequency/intensity pairs, newline-separated |
+| `max_new_tokens` | int | 512 | Max generation tokens |
+
+**Response** includes `poscar`, `structure` (formula, spacegroup, num_atoms), `raw_output`, `prompt`, `peak_text`, `inference_time`.
+
+---
+
+### `GET /ramangpt/query` — Direct RamanGPT prediction (GET)
+
+```bash
+curl "https://atomgpt.org/ramangpt/query?formula=SrTeO3&peaks=135.2cm-1(0.024),257.0cm-1(0.091),701.6cm-1(1.000)&max_new_tokens=512" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "accept: application/json"
+```
+
+| Param | Description |
+|-------|-------------|
+| `formula` | Chemical formula |
+| `peaks` | Peaks as `freq_cm-1(intensity)` comma-separated |
+| `max_new_tokens` | Max generation tokens (default 512) |
+
+Returns plain-text POSCAR of the predicted structure.
+
+---
+
+### `POST /raman/alignn` — Predict Raman spectrum from POSCAR
+
+Uses the ALIGNN `jv_raman_alignn` model to predict a 200-point Raman spectrum (50–1000 cm⁻¹) from a crystal structure.
+
+```bash
+curl -X POST "https://atomgpt.org/raman/alignn" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "poscar": "Si2\n1.0\n3.364 0.0 1.942\n1.121 3.172 1.942\n0.0 0.0 3.885\nSi\n2\nCartesian\n3.925 2.775 6.798\n0.561 0.396 0.971"
+  }'
+```
+
+**Response** includes `x_axis` (200 points, 50–1000 cm⁻¹), `y_axis`, `y_normalized`, `peaks` (top 20 with freq/intensity/normalized), `formula`, `spacegroup`, `lattice`, `inference_time`.
+
+---
+
+## Python Examples
+
+=== "Match spectrum"
+
+    ```python
+    import requests
+
+    response = requests.post(
+        "https://atomgpt.org/raman/match",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={
+            "frequencies": [135.2, 257.0, 418.3, 594.7, 701.6],
+            "activities": [0.024, 0.091, 0.083, 0.340, 1.000],
+            "formula": "SrTeO3",
+            "sigma": 8.0,
+            "top_n": 5,
+        },
+    )
+    data = response.json()
+    for m in data["matches"]:
+        print(f"{m['id']:12s} {m['formula']:10s} sim={m['similarity']:.3f}")
+    ```
+
+=== "RamanGPT"
+
+    ```python
+    import requests
+
+    response = requests.post(
+        "https://atomgpt.org/raman/ramangpt",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={
+            "formula": "SrTeO3",
+            "raman_data": "135.2  0.024\n257.0  0.091\n701.6  1.000",
+            "max_new_tokens": 512,
+        },
+    )
+    data = response.json()
+    if data["success"]:
+        print(f"Formula: {data['structure']['formula']}")
+        print(f"Spacegroup: {data['structure']['spacegroup']}")
+        print(f"POSCAR:\n{data['poscar'][:300]}")
+    ```
+
+=== "ALIGNN Raman"
+
+    ```python
+    import requests
+
+    SI_POSCAR = """Si2
+    1.0
+    3.364 0.0 1.942
+    1.121 3.172 1.942
+    0.0 0.0 3.885
+    Si
+    2
+    Cartesian
+    3.925 2.775 6.798
+    0.561 0.396 0.971"""
+
+    response = requests.post(
+        "https://atomgpt.org/raman/alignn",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={"poscar": SI_POSCAR},
+    )
+    data = response.json()
+    if data["success"]:
+        print(f"Formula: {data['formula']}, Peaks: {data['n_peaks']}")
+        for p in data["peaks"][:5]:
+            print(f"  {p['freq']} cm-1  intensity={p['intensity']:.4e}")
+    ```
+
+=== "Lookup by ID"
+
+    ```python
+    import requests
+
+    response = requests.post(
+        "https://atomgpt.org/raman/lookup",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={"material_id": "JVASP-1002"},
+    )
+    data = response.json()
+    if data["success"]:
+        print(f"Formula: {data['formula']}")
+        for f, a in zip(data["freq_cm"], data["raman_activity"]):
+            print(f"  {f:.1f} cm-1  activity={a:.4f}")
+    ```
+
+## AGAPI Agent [WIP]
 
 ```python
 from agapi.agents import AGAPIAgent
 import os
 
 agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
-response = agent.query_sync("Show raman matching for Silicon")
+
+# Match a spectrum
+response = agent.query_sync("Match Raman spectrum for SrTeO3: 135 0.02, 257 0.09, 702 1.0")
+print(response)
+
+# Predict structure from Raman
+response = agent.query_sync("Use RamanGPT to predict the structure of TiO2 from Raman peaks at 144, 399, 639 cm-1")
+print(response)
+
+# Predict Raman from structure
+response = agent.query_sync("Predict the Raman spectrum of JVASP-1002 using ALIGNN")
 print(response)
 ```
 
-## Reference
+## References
 
-- Comp. Mat. Sci. 259, 114063 (2025)
+- Computational Raman Database [:material-link: DOI](https://ramandb.oulu.fi/)
+- npj Comp. Mat. 7, 185 (2021) — ALIGNN [:material-link: DOI](https://doi.org/10.1038/s41524-021-00650-1)
+- [atomgptlab/atomgpt](https://github.com/atomgptlab/atomgpt)
diff --git a/docs/apps/characterize/xrd.md b/docs/apps/characterize/xrd.md
index c821d3e..c948c99 100644
--- a/docs/apps/characterize/xrd.md
+++ b/docs/apps/characterize/xrd.md
@@ -4,7 +4,7 @@ title: XRD / DiffractGPT
 
 # XRD / DiffractGPT
 
-XRD analysis suite: simulate powder XRD patterns from crystal structures, match experimental data to JARVIS-DFT, Rietveld-style refinement, AI-powered peak identification via DiffractGPT, POSCAR to XYZ conversion.
+XRD analysis suite: simulate powder XRD patterns from crystal structures, match experimental data to JARVIS-DFT and COD, Rietveld-style refinement, AI-powered structure prediction via DiffractGPT, and optional ALIGNN/SlakoNet property predictions on structures.
 
 [:material-open-in-new: Open App](https://atomgpt.org/xrd){ .md-button .md-button--primary }
 
@@ -12,44 +12,200 @@ XRD analysis suite: simulate powder XRD patterns from crystal structures, match
 
 ## Overview
 
-XRD analysis suite: simulate powder XRD patterns from crystal structures, match experimental data to JARVIS-DFT, Rietveld-style refinement, AI-powered peak identification via DiffractGPT, POSCAR to XYZ conversion.
+The XRD app provides a full pipeline from experimental diffraction data to crystal structure identification and property prediction. Three analysis methods are available: cosine-similarity pattern matching against JARVIS-DFT + COD databases, AI-powered structure generation via DiffractGPT, and Rietveld refinement via DARA. Results include best-match POSCAR, similarity scores, overlay plots, and optional ALIGNN/SlakoNet predictions.
 
 !!! info "Data Source"
-    **dft_3d + DiffractGPT model**
+    **dft_3d** (76K materials) + **COD** (Crystallography Open Database) for pattern matching.
+    **DiffractGPT** model for AI structure prediction from peaks.
 
 ## Endpoints
 
-- `GET /xrd`
-- `POST /xrd/query`
-- `GET /pxrd/query`
-- `GET /xrd/analyze`
-- `POST /xrd/analyze`
-- `POST /xrd/analyze_with_refinement`
-- `GET /diffractgpt/query`
-- `POST /xrd/poscar_to_xyz`
-- `POST /xrd/generate`
+### `POST /xrd/analyze` — Match XRD pattern to structures
+
+```bash
+curl -X POST "https://atomgpt.org/xrd/analyze" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "formula": "Si",
+    "xrd_data": "28.44 1.00\n47.30 0.55\n56.12 0.30\n69.13 0.06\n76.38 0.11",
+    "wavelength": 1.54184,
+    "method": "pattern_matching",
+    "interval": 0.1,
+    "x_range_min": 0.0,
+    "x_range_max": 90.0
+  }'
+```
+
+**Options for `method`:** `"pattern_matching"` (default), `"diffractgpt"`, or `"both"`.
+
+Use DiffractGPT:
+
+```bash
+curl -X POST "https://atomgpt.org/xrd/analyze" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "formula": "LaB6",
+    "xrd_data": "21.36 1.00\n30.39 0.64\n37.44 0.31\n43.51 0.20",
+    "method": "diffractgpt"
+  }'
+```
+
+Run both methods:
+
+```bash
+curl -X POST "https://atomgpt.org/xrd/analyze" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "formula": "SrTiO3",
+    "xrd_data": "22.75 0.30\n32.40 1.00\n39.95 0.45\n46.47 0.60\n57.79 0.25",
+    "method": "both"
+  }'
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `formula` | string | required | Chemical formula (e.g. `"Si"`, `"LaB6"`, `"SrTiO3"`) |
+| `xrd_data` | string | required | `2theta intensity` pairs, newline-separated |
+| `wavelength` | float | 1.54184 | X-ray wavelength in Å (Cu Kα) |
+| `method` | string | `"pattern_matching"` | `"pattern_matching"`, `"diffractgpt"`, or `"both"` |
+| `interval` | float | 0.1 | 2θ interpolation step (degrees) |
+| `x_range_min` | float | 0.0 | Minimum 2θ range |
+| `x_range_max` | float | 90.0 | Maximum 2θ range |
+
+---
 
-**Request Models:** `XRDAnalysisRequest`, `XRDRefinementRequest`, `XRDGenerateRequest`
+### `POST /xrd/analyze_with_refinement` — Full pipeline with Rietveld + ALIGNN
+
+```bash
+curl -X POST "https://atomgpt.org/xrd/analyze_with_refinement" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "formula": "Si",
+    "xrd_data": "28.44 1.00\n47.30 0.55\n56.12 0.30",
+    "wavelength": 1.54184,
+    "method": "both",
+    "run_refinement": true,
+    "run_alignn": true,
+    "run_slakonet": false
+  }'
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `formula` | string | required | Chemical formula |
+| `xrd_data` | string | required | 2θ/intensity data |
+| `wavelength` | float | 1.54184 | X-ray wavelength (Å) |
+| `method` | string | `"pattern_matching"` | `"pattern_matching"`, `"diffractgpt"`, or `"both"` |
+| `run_refinement` | bool | `true` | Run Rietveld refinement on best match |
+| `run_alignn` | bool | `false` | Predict properties with ALIGNN on matched structure |
+| `run_slakonet` | bool | `false` | Compute band structure with SlakoNet |
+| `best_match_poscar` | string | `""` | Override starting structure for refinement |
+
+Pipeline steps: (1) Pattern matching → (2) DiffractGPT → (3) Rietveld refinement → (4) ALIGNN/SlakoNet predictions.
+
+---
 
-!!! note "Authentication"
-    All POST endpoints require `Authorization: Bearer YOUR_TOKEN`.
+### `POST /xrd/generate` — Generate XRD from POSCAR
+
+```bash
+curl -X POST "https://atomgpt.org/xrd/generate" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "poscar": "Si\n1.0\n0 2.734 2.734\n2.734 0 2.734\n2.734 2.734 0\nSi\n2\ndirect\n0 0 0\n0.25 0.25 0.25",
+    "wavelength": 1.54184
+  }'
+```
+
+Returns `two_thetas`, `d_hkls`, `intensities` (normalized to 100), formula, spacegroup, lattice parameters.
 
-## API Example
+---
+
+### `GET /diffractgpt/query` — Direct DiffractGPT prediction
+
+```bash
+curl "https://atomgpt.org/diffractgpt/query?formula=Si&peaks=28.4(1.0),47.3(0.55),56.1(0.30)&max_new_tokens=456" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "accept: application/json"
+```
+
+| Param | Description |
+|-------|-------------|
+| `formula` | Chemical formula |
+| `peaks` | Peaks as `2theta(intensity)` comma-separated |
+| `max_new_tokens` | Max generation tokens (default 456) |
+
+Returns plain-text POSCAR of the predicted structure.
+
+---
+
+### `GET /pxrd/query` — Legacy PXRD pattern matching
+
+```bash
+curl "https://atomgpt.org/pxrd/query?pattern=Si%0A28.44%201.00%0A47.30%200.55%0A56.12%200.30&intvl=0.1&x_min=0&x_max=90" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "accept: application/json"
+```
+
+Pattern format: first line = formula, subsequent lines = `2theta intensity`. URL-encode newlines as `%0A`.
+
+---
+
+### `POST /xrd/poscar_to_xyz` — Convert POSCAR to XYZ
+
+```bash
+curl -X POST "https://atomgpt.org/xrd/poscar_to_xyz" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{"poscar": "Si\n1.0\n0 2.734 2.734\n2.734 0 2.734\n2.734 2.734 0\nSi\n2\ndirect\n0 0 0\n0.25 0.25 0.25"}'
+```
+
+---
+
+## Python Example
 
 ```python
 import requests
 
 response = requests.post(
-    "https://atomgpt.org/xrd/query",
+    "https://atomgpt.org/xrd/analyze",
     headers={
         "Authorization": "Bearer sk-XYZ",
         "accept": "application/json",
         "Content-Type": "application/json",
     },
-    json={"jid": "JVASP-1002"},
+    json={
+        "formula": "Si",
+        "xrd_data": "28.44 1.00\n47.30 0.55\n56.12 0.30",
+        "method": "both",
+    },
 )
 data = response.json()
-print(data)
+
+# Pattern matching result
+pm = data.get("pattern_matching", {})
+if pm.get("success"):
+    best = pm["best_match"]
+    print(f"Best match: {best['jid']} ({best['formula']})")
+    print(f"Similarity: {best['similarity']*100:.1f}%")
+    print(f"POSCAR:\n{best['poscar'][:200]}")
+
+# DiffractGPT result
+dg = data.get("diffractgpt", {})
+if dg.get("success"):
+    s = dg["structure"]
+    print(f"DiffractGPT: {s['formula']} ({s['spacegroup']})")
+    print(f"Similarity: {s['similarity']*100:.1f}%")
 ```
 
 ## AGAPI Agent
@@ -59,10 +215,12 @@ from agapi.agents import AGAPIAgent
 import os
 
 agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
-response = agent.query_sync("Show xrd / diffractgpt for Silicon")
+response = agent.query_sync("Match this XRD pattern for Silicon: 28.44 1.00, 47.30 0.55, 56.12 0.30")
 print(response)
 ```
 
 ## Reference
 
-- J. Phys. Chem. Lett. 16, 2110 (2025)
+- J. Phys. Chem. Lett. 16, 2110 (2025) — DiffractGPT [:material-link: DOI](https://pubs.acs.org/doi/10.1021/acs.jpclett.4c03137)
+- [atomgptlab/jarvis](https://github.com/atomgptlab/jarvis/blob/master/jarvis/analysis/diffraction/xrd.py)
+- [atomgptlab/agapi](https://github.com/atomgptlab/agapi)
diff --git a/docs/apps/explore/convexhull.md b/docs/apps/explore/convexhull.md
index cfbb788..02e50cc 100644
--- a/docs/apps/explore/convexhull.md
+++ b/docs/apps/explore/convexhull.md
@@ -4,7 +4,7 @@ title: Convex Hull
 
 # Convex Hull
 
-Convex hull phase diagram from JARVIS-DFT formation energies. Supports 2-element (2D plot), 3-element (ternary), and 4+-element (3D) systems.
+Compute convex hull phase diagrams from JARVIS-DFT formation energies. Supports 2-element (binary 2D plot), 3-element (ternary triangle), and 4+-element (3D tetrahedron) systems. Based on `jarvis.analysis.thermodynamics.energetics.PhaseDiagram`. Returns hull vertices, simplices, and per-entry stability classification.
 
 [:material-open-in-new: Open App](https://atomgpt.org/convexhull){ .md-button .md-button--primary }
 
@@ -12,50 +12,67 @@ Convex hull phase diagram from JARVIS-DFT formation energies. Supports 2-element
 
 ## Overview
 
-Convex hull phase diagram from JARVIS-DFT formation energies. Supports 2-element (2D plot), 3-element (ternary), and 4+-element (3D) systems.
-
 !!! info "Data Source"
-    **dft_3d (formation energies)**
+    **JARVIS dft_3d** — formation energies via `PhaseDiagram` from jarvis-tools.
 
 ## Endpoints
 
-- `GET /convexhull`
-- `POST /convexhull/compute`
+### `POST /convexhull/compute` — Compute phase diagram
 
-**Request Models:** `ConvexHullRequest`
+```bash
+curl -X POST "https://atomgpt.org/convexhull/compute" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -d '{"elements": "Ni-Al", "only_stable": false}'
+```
 
-!!! note "Authentication"
-    All POST endpoints require `Authorization: Bearer YOUR_TOKEN`.
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `elements` | string | required | Dash-separated elements (e.g. `Ni-Al`, `Ni-Al-O`) |
+| `only_stable` | bool | false | Only plot hull-stable phases |
 
-## API Example
+**Response varies by dimensionality:**
+
+- **Binary (2 elements):** `plot_type: "2d"`, x (composition), e (energy), names, hull (bool array), simplices (line segments)
+- **Ternary (3 elements):** `plot_type: "ternary"`, a/b (triangle coords), hull, simplices (triangles)
+- **Quaternary+ (4+ elements):** `plot_type: "3d"`, a/b/c (tetrahedron coords), hull, simplices
+
+All include `entries` array with formula, jid, energy, on_hull flag.
+
+
+---
+
+## Python Examples
+
+=== "Binary hull"
+
+    ```python
+    import requests
+
+    response = requests.post(
+        "https://atomgpt.org/convexhull/compute",
+        headers={"Authorization": "Bearer sk-XYZ", "Content-Type": "application/json"},
+        json={"elements": "Ni-Al"},
+    )
+    data = response.json()
+    stable = [e for e in data["entries"] if e["on_hull"]]
+    print(f"Ni-Al system: {data['n_entries']} entries, {len(stable)} on hull")
+    for s in stable:
+        print(f"  {s['formula']}: {s['energy']:.3f} eV/atom")
+    ```
 
-```python
-import requests
-
-response = requests.post(
-    "https://atomgpt.org/convexhull/compute",
-    headers={
-        "Authorization": "Bearer sk-XYZ",
-        "accept": "application/json",
-        "Content-Type": "application/json",
-    },
-    json={"jid": "JVASP-1002"},
-)
-data = response.json()
-print(data)
-```
 
 ## AGAPI Agent
 
 ```python
 from agapi.agents import AGAPIAgent
 import os
-
 agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
-response = agent.query_sync("Show convex hull for Silicon")
+response = agent.query_sync("Show convex hull data")
 print(response)
 ```
 
-## Reference
+## References
 
-- NPJ Comp. Mat. 6, 173 (2020)
+- K. Choudhary et al., npj Comp. Mat. 6, 173 (2020) [:material-link: DOI](https://doi.org/10.1038/s41524-020-00440-1)
+- [atomgptlab/jarvis](https://github.com/atomgptlab/jarvis)
diff --git a/docs/apps/explore/dielectric-function.md b/docs/apps/explore/dielectric-function.md
index 481d2e1..9f19d88 100644
--- a/docs/apps/explore/dielectric-function.md
+++ b/docs/apps/explore/dielectric-function.md
@@ -4,7 +4,7 @@ title: Dielectric Function
 
 # Dielectric Function
 
-Look up and interactively plot the MBJ dielectric function ε(ω) for any JARVIS-DFT material. Supports search by JARVIS ID, chemical formula, space group, and MBJ band gap range.
+Look up and interactively plot the MBJ dielectric function ε(ω) for any JARVIS-DFT material. Returns real and imaginary parts of the dielectric tensor (xx, yy, zz components) plus computed averages. Data fetched via `Webpage.get_dft_mbj_dielectric_function()`.
 
 [:material-open-in-new: Open App](https://atomgpt.org/dielectric_function){ .md-button .md-button--primary }
 
@@ -12,40 +12,116 @@ Look up and interactively plot the MBJ dielectric function ε(ω) for any JARVIS
 
 ## Overview
 
-Look up and interactively plot the MBJ dielectric function ε(ω) for any JARVIS-DFT material. Supports search by JARVIS ID, chemical formula, space group, and MBJ band gap range.
+Search materials by formula, JARVIS ID, elements, space group, or property ranges. Click any result to fetch and plot the full spectrum. All search results are capped at 500 entries.
 
 !!! info "Data Source"
-    **dft_3d**
+    **JARVIS-DFT** — MBJ dielectric function via `jarvis.db.webpages.Webpage.get_dft_mbj_dielectric_function()`.
 
 ## Endpoints
 
-- `GET /dielectric_function`
-- `POST /dielectric_function/search`
-- `GET /dielectric_function/data/{jid}`
+### `POST /dielectric_function/search` — Search materials
 
-**Request Models:** `DielectricSearchRequest`
+```bash
+curl -X POST "https://atomgpt.org/dielectric_function/search" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "formula": "Si"
+  }'
+```
+
+Search with elements:
+
+```bash
+curl -X POST "https://atomgpt.org/dielectric_function/search" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "elements": ["Ti", "O"],
+    "element_mode": "all"
+  }'
+```
 
-!!! note "Authentication"
-    All POST endpoints require `Authorization: Bearer YOUR_TOKEN`.
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `formula` | string | null | Chemical formula |
+| `jid` | string | null | Exact JARVIS ID |
+| `elements` | list[string] | null | Element symbols |
+| `element_mode` | string | "any" | "any", "all", or "exact" |
+| `bandgap_min` | float | null | Min MBJ band gap (eV) |
+| `bandgap_max` | float | null | Max MBJ band gap (eV) |
 
-## API Example
+**Response fields:** `jid, formula, spacegroup, mbj_bandgap, optb88vdw_bandgap`.
 
-```python
-import requests
-
-response = requests.post(
-    "https://atomgpt.org/dielectric_function/search",
-    headers={
-        "Authorization": "Bearer sk-XYZ",
-        "accept": "application/json",
-        "Content-Type": "application/json",
-    },
-    json={"jid": "JVASP-1002"},
-)
-data = response.json()
-print(data)
+---
+
+### `GET /dielectric_function/data/{jid}` — Fetch spectrum data
+
+Fetch MBJ dielectric function ε(ω) for a single material. Returns energy axis, real/imaginary xx/yy/zz components, and computed averages.
+
+```bash
+curl "https://atomgpt.org/dielectric_function/data/JVASP-1002" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "accept: application/json"
+```
+
+**Response:**
+
+```json
+{
+  "jid": "JVASP-1002",
+  "formula": "Si",
+  "energies": [0.0, 0.1, 0.2, ...],
+  "components": {
+    "imag_xx": [...], "imag_yy": [...], "imag_zz": [...],
+    "real_xx": [...], "real_yy": [...], "real_zz": [...],
+    "imag_avg": [...], "real_avg": [...]
+  }
+}
 ```
 
+8 components: `imag_xx/yy/zz`, `real_xx/yy/zz`, plus computed `imag_avg` and `real_avg` (arithmetic mean of xx/yy/zz).
+
+---
+
+## Python Examples
+
+=== "Search"
+
+    ```python
+    import requests
+
+    response = requests.post(
+        "https://atomgpt.org/dielectric_function/search",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={"formula": "Si"},
+    )
+    data = response.json()
+    print(f"Found {data['total']} materials")
+    for m in data["results"][:5]:
+        print(f"  {m['jid']}: {m['formula']}")
+    ```
+
+=== "Fetch data"
+
+    ```python
+    import requests
+
+    response = requests.get(
+        "https://atomgpt.org/dielectric_function/data/JVASP-1002",
+        headers={"Authorization": "Bearer sk-XYZ"},
+    )
+    data = response.json()
+    print(f"{data['formula']} — {len(data['energies'])} energy points")
+    print(f"Components: {list(data['components'].keys())}")
+    ```
+
 ## AGAPI Agent
 
 ```python
@@ -57,6 +133,7 @@ response = agent.query_sync("Show dielectric function for Silicon")
 print(response)
 ```
 
-## Reference
+## References
 
-- Nature Sci. Data 5, 180082 (2018)
+- K. Choudhary et al., Nature Sci. Data 5, 180082 (2018) [:material-link: DOI](https://doi.org/10.1038/sdata.2018.82)
+- [atomgptlab/jarvis](https://github.com/atomgptlab/jarvis)
diff --git a/docs/apps/explore/efg.md b/docs/apps/explore/efg.md
index 4d142c7..64fcff8 100644
--- a/docs/apps/explore/efg.md
+++ b/docs/apps/explore/efg.md
@@ -1,10 +1,10 @@
 ---
-title: EFG
+title: EFG Explorer
 ---
 
-# EFG
+# EFG Explorer
 
-Visualize and compare electric field gradient (EFG) tensors from JARVIS-DFT for NMR/NQR applications. Vzz, asymmetry parameter η, quadrupole coupling constants parsed from JARVIS XML.
+Visualize and compare electric field gradient (EFG) tensors from JARVIS-DFT for NMR/NQR applications. Per-site 3×3 EFG tensors with element and Wyckoff labels, max EFG (Vzz), and asymmetry parameter η. Data parsed from JARVIS XML `<efg_raw_tensor>` section.
 
 [:material-open-in-new: Open App](https://atomgpt.org/efg){ .md-button .md-button--primary }
 
@@ -12,40 +12,96 @@ Visualize and compare electric field gradient (EFG) tensors from JARVIS-DFT for
 
 ## Overview
 
-Visualize and compare electric field gradient (EFG) tensors from JARVIS-DFT for NMR/NQR applications. Vzz, asymmetry parameter η, quadrupole coupling constants parsed from JARVIS XML.
-
 !!! info "Data Source"
-    **dft_3d (JARVIS XML)**
+    **JARVIS-DFT** — EFG tensors parsed from JARVIS XML (`<efg_raw_tensor>` tag).
 
 ## Endpoints
 
-- `GET /efg`
-- `POST /efg/search`
-- `GET /efg/data/{jid}`
+### `POST /efg/search` — Search materials
 
-**Request Models:** `EFGSearchRequest`
+```bash
+curl -X POST "https://atomgpt.org/efg/search" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{"formula": "Si"}'
+```
 
-!!! note "Authentication"
-    All POST endpoints require `Authorization: Bearer YOUR_TOKEN`.
+Standard search fields: `formula`, `jid`, `elements`, `element_mode` (any/all/exact), `bandgap_min`, `bandgap_max`, `spacegroup`. Max 500 results.
 
-## API Example
+!!! note
+    Pre-filtered to materials with `max_efg != 'na'`.
 
-```python
-import requests
-
-response = requests.post(
-    "https://atomgpt.org/efg/search",
-    headers={
-        "Authorization": "Bearer sk-XYZ",
-        "accept": "application/json",
-        "Content-Type": "application/json",
-    },
-    json={"jid": "JVASP-1002"},
-)
-data = response.json()
-print(data)
+---
+
+### `GET /efg/data/{jid}` — Fetch per-site 3×3 EFG tensors for a single material.
+
+```bash
+curl "https://atomgpt.org/efg/data/JVASP-1002" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "accept: application/json"
 ```
 
+**Response:**
+
+```json
+{
+  "jid": "JVASP-1002",
+  "formula": "Si",
+  "bandgap": 0.611,
+  "max_efg": 0.001,
+  "max_efg_eta": null,
+  "sites": [
+    {
+      "element": "Si",
+      "wyckoff": "a",
+      "tensor": [[0.001, 0.0, 0.0], [0.0, 0.001, 0.0], [0.0, 0.0, -0.002]]
+    }
+  ]
+}
+```
+
+EFG tensor format in XML: `Element,Wyckoff,xx,xy,xz,yx,yy,yz,zx,zy,zz;` semicolon-separated sites. Returns per-site 3×3 tensor, element, Wyckoff label, plus scalar `max_efg` and `max_efg_eta`.
+
+---
+
+## Python Examples
+
+=== "Search"
+
+    ```python
+    import requests
+
+    response = requests.post(
+        "https://atomgpt.org/efg/search",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={"formula": "Si"},
+    )
+    data = response.json()
+    print(f"Found {data['total']} entries")
+    for m in data["results"][:5]:
+        print(f"  {m['jid']}: {m.get('formula', m.get('bulk_formula', ''))}")
+    ```
+
+=== "Fetch data"
+
+    ```python
+    import requests
+
+    response = requests.get(
+        "https://atomgpt.org/efg/data/JVASP-1002",
+        headers={"Authorization": "Bearer sk-XYZ"},
+    )
+    data = response.json()
+    print(f"{data['formula']} — max EFG: {data['max_efg']}")
+    for site in data["sites"]:
+        print(f"  {site['element']} ({site['wyckoff']}): Vzz={site['tensor'][2][2]:.4f}")
+    ```
+
 ## AGAPI Agent
 
 ```python
@@ -53,10 +109,11 @@ from agapi.agents import AGAPIAgent
 import os
 
 agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
-response = agent.query_sync("Show efg for Silicon")
+response = agent.query_sync("Show efg explorer for Silicon")
 print(response)
 ```
 
-## Reference
+## References
 
-- Nature Sci. Data 7, 362 (2020)
+- K. Choudhary et al., Nature Sci. Data 7, 362 (2020) [:material-link: DOI](https://doi.org/10.1038/s41597-020-00707-8)
+- [atomgptlab/jarvis](https://github.com/atomgptlab/jarvis)
diff --git a/docs/apps/explore/elastic-tensor.md b/docs/apps/explore/elastic-tensor.md
index 6ed31bc..df2277b 100644
--- a/docs/apps/explore/elastic-tensor.md
+++ b/docs/apps/explore/elastic-tensor.md
@@ -4,7 +4,7 @@ title: Elastic Tensor
 
 # Elastic Tensor
 
-Visualize and compare the 6×6 elastic stiffness tensor Cij for any JARVIS-DFT material. Search by JARVIS ID, formula, elements, space group, and modulus ranges. Heatmap, matrix, and comparison views.
+Visualize and compare the 6×6 elastic stiffness tensor Cij for any JARVIS-DFT material. Search by formula, elements, space group, and bulk/shear modulus ranges. The data endpoint returns the full tensor plus Voigt-Reuss-Hill derived mechanical properties (bulk/shear modulus, Young's modulus, Poisson ratio, Pugh ratio).
 
 [:material-open-in-new: Open App](https://atomgpt.org/elastic_tensor){ .md-button .md-button--primary }
 
@@ -12,40 +12,138 @@ Visualize and compare the 6×6 elastic stiffness tensor Cij for any JARVIS-DFT m
 
 ## Overview
 
-Visualize and compare the 6×6 elastic stiffness tensor Cij for any JARVIS-DFT material. Search by JARVIS ID, formula, elements, space group, and modulus ranges. Heatmap, matrix, and comparison views.
+Search materials by formula, JARVIS ID, elements, space group, or property ranges. Click any result to fetch and plot the full spectrum. All search results are capped at 500 entries.
 
 !!! info "Data Source"
-    **dft_3d**
+    **JARVIS-DFT** — `elastic_tensor` field in `dft_3d` dataset (no XML fetch needed).
 
 ## Endpoints
 
-- `GET /elastic_tensor`
-- `POST /elastic_tensor/search`
-- `GET /elastic_tensor/data/{jid}`
+### `POST /elastic_tensor/search` — Search materials
 
-**Request Models:** `ElasticSearchRequest`
+```bash
+curl -X POST "https://atomgpt.org/elastic_tensor/search" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "formula": "Si"
+  }'
+```
+
+Search with elements:
+
+```bash
+curl -X POST "https://atomgpt.org/elastic_tensor/search" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "elements": ["Ti", "O"],
+    "element_mode": "all"
+  }'
+```
 
-!!! note "Authentication"
-    All POST endpoints require `Authorization: Bearer YOUR_TOKEN`.
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `formula` | string | null | Chemical formula |
+| `jid` | string | null | Exact JARVIS ID |
+| `elements` | list[string] | null | Element symbols |
+| `element_mode` | string | "any" | "any", "all", or "exact" |
+| `bulk_modulus_min` | float | null | Min bulk modulus Kv (GPa) |
+| `bulk_modulus_max` | float | null | Max bulk modulus Kv (GPa) |
+| `shear_modulus_min` | float | null | Min shear modulus Gv (GPa) |
+| `shear_modulus_max` | float | null | Max shear modulus Gv (GPa) |
+| `spacegroup` | string | null | Space group substring |
 
-## API Example
+**Response fields:** `jid, formula, spacegroup, crys, bulk_modulus_kv, shear_modulus_gv, poisson, density`.
 
-```python
-import requests
-
-response = requests.post(
-    "https://atomgpt.org/elastic_tensor/search",
-    headers={
-        "Authorization": "Bearer sk-XYZ",
-        "accept": "application/json",
-        "Content-Type": "application/json",
-    },
-    json={"jid": "JVASP-1002"},
-)
-data = response.json()
-print(data)
+---
+
+### `GET /elastic_tensor/data/{jid}` — Fetch spectrum data
+
+Fetch the full 6×6 elastic tensor and Voigt-Reuss-Hill derived properties for a single material.
+
+```bash
+curl "https://atomgpt.org/elastic_tensor/data/JVASP-1002" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "accept: application/json"
+```
+
+**Response:**
+
+```json
+{
+  "jid": "JVASP-1002",
+  "formula": "Si",
+  "spacegroup": "Fd-3m",
+  "crys": "cubic",
+  "density": 2.329,
+  "tensor": [[165.77, 63.93, 63.93, 0, 0, 0], ...],
+  "derived": {
+    "bulk_modulus_voigt": 97.88,
+    "bulk_modulus_reuss": 97.88,
+    "bulk_modulus_vrh": 97.88,
+    "shear_modulus_voigt": 60.23,
+    "shear_modulus_reuss": 49.73,
+    "shear_modulus_vrh": 54.98,
+    "youngs_modulus": 139.72,
+    "poisson_ratio": 0.2703,
+    "pugh_ratio": 1.78
+  },
+  "stored": {
+    "bulk_modulus_kv": 97.88,
+    "shear_modulus_gv": 60.23,
+    "poisson": 0.27
+  }
+}
 ```
 
+Tensor is 6×6 Voigt notation (GPa). Derived properties computed via Voigt-Reuss-Hill averaging. `stored` contains the pre-computed values from JARVIS-DFT for cross-reference.
+
+---
+
+## Python Examples
+
+=== "Search"
+
+    ```python
+    import requests
+
+    response = requests.post(
+        "https://atomgpt.org/elastic_tensor/search",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={"formula": "Si"},
+    )
+    data = response.json()
+    print(f"Found {data['total']} materials")
+    for m in data["results"][:5]:
+        print(f"  {m['jid']}: {m['formula']}")
+    ```
+
+=== "Fetch data"
+
+    ```python
+    import requests
+
+    response = requests.get(
+        "https://atomgpt.org/elastic_tensor/data/JVASP-1002",
+        headers={"Authorization": "Bearer sk-XYZ"},
+    )
+    data = response.json()
+    d = data["derived"]
+    print(f"{data['formula']} ({data['crys']})")
+    print(f"  Bulk modulus (VRH): {d['bulk_modulus_vrh']} GPa")
+    print(f"  Shear modulus (VRH): {d['shear_modulus_vrh']} GPa")
+    print(f"  Young's modulus: {d['youngs_modulus']} GPa")
+    print(f"  Poisson ratio: {d['poisson_ratio']}")
+    print(f"  Pugh ratio: {d['pugh_ratio']}")
+    ```
+
 ## AGAPI Agent
 
 ```python
@@ -57,6 +155,7 @@ response = agent.query_sync("Show elastic tensor for Silicon")
 print(response)
 ```
 
-## Reference
+## References
 
-- Phys. Rev. B 98, 014107 (2018)
+- K. Choudhary et al., Phys. Rev. B 98, 014107 (2018) [:material-link: DOI](https://doi.org/10.1103/PhysRevB.98.014107)
+- [atomgptlab/jarvis](https://github.com/atomgptlab/jarvis)
diff --git a/docs/apps/explore/electronic-dos.md b/docs/apps/explore/electronic-dos.md
index f43c961..40ad442 100644
--- a/docs/apps/explore/electronic-dos.md
+++ b/docs/apps/explore/electronic-dos.md
@@ -4,7 +4,7 @@ title: Electronic DOS
 
 # Electronic DOS
 
-Visualize and compare the electronic density of states from JARVIS-DFT. Spin-resolved up/down channels fetched from JARVIS XML pages.
+Visualize and compare the electronic density of states from JARVIS-DFT. Spin-resolved up/down channels with total DOS. Search materials by formula, elements, space group, or band gap range, then fetch DOS spectra from JARVIS XML pages via `Webpage.get_dft_electron_dos()`.
 
 [:material-open-in-new: Open App](https://atomgpt.org/electronic_dos){ .md-button .md-button--primary }
 
@@ -12,40 +12,118 @@ Visualize and compare the electronic density of states from JARVIS-DFT. Spin-res
 
 ## Overview
 
-Visualize and compare the electronic density of states from JARVIS-DFT. Spin-resolved up/down channels fetched from JARVIS XML pages.
+Search materials by formula, JARVIS ID, elements, space group, or property ranges. Click any result to fetch and plot the full spectrum. All search results are capped at 500 entries.
 
 !!! info "Data Source"
-    **dft_3d (JARVIS XML)**
+    **JARVIS-DFT** — electronic DOS fetched via `jarvis.db.webpages.Webpage.get_dft_electron_dos()`.
 
 ## Endpoints
 
-- `GET /electronic_dos`
-- `POST /electronic_dos/search`
-- `GET /electronic_dos/data/{jid}`
+### `POST /electronic_dos/search` — Search materials
 
-**Request Models:** `DOSSearchRequest`
+```bash
+curl -X POST "https://atomgpt.org/electronic_dos/search" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "formula": "Si"
+  }'
+```
+
+Search with elements:
+
+```bash
+curl -X POST "https://atomgpt.org/electronic_dos/search" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "elements": ["Ti", "O"],
+    "element_mode": "all"
+  }'
+```
 
-!!! note "Authentication"
-    All POST endpoints require `Authorization: Bearer YOUR_TOKEN`.
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `formula` | string | null | Chemical formula (auto-reduced) |
+| `jid` | string | null | Exact JARVIS ID |
+| `elements` | list[string] | null | Element symbols |
+| `element_mode` | string | "any" | "any", "all", or "exact" |
+| `bandgap_min` | float | null | Min OptB88vdW band gap (eV) |
+| `bandgap_max` | float | null | Max OptB88vdW band gap (eV) |
+| `spacegroup` | string | null | Space group substring |
 
-## API Example
+**Response fields:** `jid, formula, spacegroup, optb88vdw_bandgap, mbj_bandgap, magmom`.
 
-```python
-import requests
-
-response = requests.post(
-    "https://atomgpt.org/electronic_dos/search",
-    headers={
-        "Authorization": "Bearer sk-XYZ",
-        "accept": "application/json",
-        "Content-Type": "application/json",
-    },
-    json={"jid": "JVASP-1002"},
-)
-data = response.json()
-print(data)
+---
+
+### `GET /electronic_dos/data/{jid}` — Fetch spectrum data
+
+Fetch electronic DOS spectrum for a single material. Returns energy axis and spin-resolved DOS channels.
+
+```bash
+curl "https://atomgpt.org/electronic_dos/data/JVASP-1002" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "accept: application/json"
+```
+
+**Response:**
+
+```json
+{
+  "jid": "JVASP-1002",
+  "formula": "Si",
+  "bandgap": 0.611,
+  "energies": [-10.0, -9.99, ...],
+  "components": {
+    "Spin Up": [0.0, 0.01, ...],
+    "Spin Down": [0.0, 0.01, ...],
+    "Total": [0.0, 0.02, ...]
+  }
+}
 ```
 
+DOS channels auto-detected from keys like `total_edos_up`/`total_edos_down`. Total computed from spin components if not present. Energy axis searched across keys: `energies`, `energy`, `edos_energies`.
+
+---
+
+## Python Examples
+
+=== "Search"
+
+    ```python
+    import requests
+
+    response = requests.post(
+        "https://atomgpt.org/electronic_dos/search",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={"formula": "Si"},
+    )
+    data = response.json()
+    print(f"Found {data['total']} materials")
+    for m in data["results"][:5]:
+        print(f"  {m['jid']}: {m['formula']}")
+    ```
+
+=== "Fetch data"
+
+    ```python
+    import requests
+
+    response = requests.get(
+        "https://atomgpt.org/electronic_dos/data/JVASP-1002",
+        headers={"Authorization": "Bearer sk-XYZ"},
+    )
+    data = response.json()
+    print(f"{data['formula']} — {len(data['energies'])} energy points")
+    print(f"Channels: {list(data['components'].keys())}")
+    ```
+
 ## AGAPI Agent
 
 ```python
@@ -57,6 +135,8 @@ response = agent.query_sync("Show electronic dos for Silicon")
 print(response)
 ```
 
-## Reference
+## References
 
-- Comp. Mat. Sci. 259, 114063 (2025); JOM 74, 1395 (2022)
+- K. Choudhary, Comp. Mat. Sci. 259, 114063 (2025) [:material-link: DOI](https://doi.org/10.1016/j.commatsci.2025.114063)
+- K. Choudhary, JOM 74, 1395 (2022) [:material-link: DOI](https://doi.org/10.1007/s11837-022-05209-3)
+- [atomgptlab/jarvis](https://github.com/atomgptlab/jarvis)
diff --git a/docs/apps/explore/ff.md b/docs/apps/explore/ff.md
index 652e8c0..480362e 100644
--- a/docs/apps/explore/ff.md
+++ b/docs/apps/explore/ff.md
@@ -4,7 +4,7 @@ title: Force Field DB
 
 # Force Field DB
 
-JARVIS Force-Field (FF) database search. Search by elements, JID, formula, crystal system, or force-field type (EAM, Tersoff, ReaxFF, etc.).
+Search the JARVIS Force-Field (JFF) database. Filter by elements, JID, formula, crystal system (space group), or force-field type (EAM, Tersoff, ReaxFF, etc.). Returns mechanical properties (Kv, Gv, Poisson, Young's modulus), surface/vacancy energies, lattice parameters, and phonon availability.
 
 [:material-open-in-new: Open App](https://atomgpt.org/ff){ .md-button .md-button--primary }
 
@@ -12,50 +12,63 @@ JARVIS Force-Field (FF) database search. Search by elements, JID, formula, cryst
 
 ## Overview
 
-JARVIS Force-Field (FF) database search. Search by elements, JID, formula, crystal system, or force-field type (EAM, Tersoff, ReaxFF, etc.).
-
 !!! info "Data Source"
-    **JARVIS-FF**
+    **JARVIS-FF (JFF)** — from `jarvis.db.figshare.data('jff')`.
 
 ## Endpoints
 
-- `GET /ff`
-- `POST /ff/search`
+### `POST /ff/search` — Search materials
 
-**Request Models:** `FFSearchRequest`
+```bash
+curl -X POST "https://atomgpt.org/ff/search" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -d '{"formula": "MoS2"}'
+```
 
-!!! note "Authentication"
-    All POST endpoints require `Authorization: Bearer YOUR_TOKEN`.
+| Field | Type | Description |
+|-------|------|-------------|
+| `elements` | string | Dash-separated elements (e.g. 'Si-Ge-') |
+| `jid` | string | JID substring |
+| `formula` | string | Formula substring |
+| `crystal_system` | string | Space group substring |
+| `forcefield` | string | Force-field type substring (e.g. 'eam', 'tersoff') |
 
-## API Example
+**Response:** `jid, formula, spg, forcefield, kv, gv, poisson, youngs_gpa, surface_energy, vacancy_energy, a/b/c, n_atoms, ref, phonon`.
+
+---
+
+
+---
+
+## Python Examples
+
+=== "Search"
+
+    ```python
+    import requests
+
+    response = requests.post(
+        "https://atomgpt.org/ff/search",
+        headers={"Authorization": "Bearer sk-XYZ", "Content-Type": "application/json"},
+        json={"formula": "Si"},
+    )
+    data = response.json()
+    print(f"Found {data['total']} entries")
+    ```
 
-```python
-import requests
-
-response = requests.post(
-    "https://atomgpt.org/ff/search",
-    headers={
-        "Authorization": "Bearer sk-XYZ",
-        "accept": "application/json",
-        "Content-Type": "application/json",
-    },
-    json={"jid": "JVASP-1002"},
-)
-data = response.json()
-print(data)
-```
 
 ## AGAPI Agent
 
 ```python
 from agapi.agents import AGAPIAgent
 import os
-
 agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
-response = agent.query_sync("Show force field db for Silicon")
+response = agent.query_sync("Show force field db data")
 print(response)
 ```
 
-## Reference
+## References
 
-- J. Phys. Cond. Matt. 30, 395901 (2018)
+- K. Choudhary et al., J. Phys.: Condens. Matter 30, 395901 (2018) [:material-link: DOI](https://doi.org/10.1088/1361-648X/aadaff)
+- [atomgptlab/jarvis](https://github.com/atomgptlab/jarvis)
diff --git a/docs/apps/explore/hardmat.md b/docs/apps/explore/hardmat.md
new file mode 100644
index 0000000..da9d5a3
--- /dev/null
+++ b/docs/apps/explore/hardmat.md
@@ -0,0 +1,70 @@
+---
+title: HardMat
+---
+
+# HardMat
+
+Predict Vickers hardness (GPa and HV) from elastic moduli using 9 semi-empirical models (H1a–H5, Tian, Mazhnik-Oganov, Lyakhov-Oganov). Two tabs: (1) JARVIS-DFT lookup — fetches Kv, Gv, bandgap, density, spacegroup from dft_3d, applies CLA1/CLA2 smart model selection (Dovale-Farelo 2022 Tables 5&6). (2) ALIGNN — predicts Kv & Gv from POSCAR, then runs all 9 models. Built-in crystal system classification from space group number, bandgap class (metal/semiconductor/insulator), and density class (low/medium/high).
+
+[:material-open-in-new: Open App](https://atomgpt.org/hardmat){ .md-button .md-button--primary }
+
+---
+
+## Overview
+
+!!! info "Data Source"
+    **JARVIS dft_3d** (Tab 1) + **ALIGNN** (Tab 2). Smart model selection from Dovale-Farelo et al., Sci. Rep. 12, 22475 (2022).
+
+## Endpoints
+
+### `POST /hardmat/jarvis` — JARVIS-DFT lookup + predict
+
+```bash
+curl -X POST "https://atomgpt.org/hardmat/jarvis" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -d '{"jid": "JVASP-1002"}'
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `jid` | string | JARVIS ID (exact match) |
+| `formula` | string | Chemical formula (hill order; selects lowest-ehull entry with elastic data) |
+
+**Response:** `jid, formula, K_GPa, G_GPa, Y_GPa, poisson, pugh_ratio, density, bandgap, spacegroup, ehull, crystal_system, bandgap_class, density_class, cla1_recommended, cla2_recommended, hardness_GPa` (9 models), `hardness_HV` (converted), `warnings`, `selection_note`.
+
+---
+
+### `POST /hardmat/alignn` — ALIGNN prediction from POSCAR
+
+```bash
+curl -X POST "https://atomgpt.org/hardmat/alignn" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -d '{"poscar": "System\n1.0\n3.26 0 0\n0 3.26 0\n0 0 3.26\nTi Au\n1 1\ndirect\n0.5 0.5 0.5 Ti\n0 0 0 Au"}'
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `poscar` | string | required | VASP POSCAR string (max 50 atoms) |
+
+**Response:** Same as JARVIS endpoint plus `alignn_props` (formation_energy, bandgap_mbj, supercon_tc).
+
+**9 hardness models:** H1a (Jiang 2011), H1b (Jiang 2011), H2 (Teter 1998), H3 (Jiang 2010), H4 (Miao 2011), H5/Chen (2011), Tian (2012), Mazhnik-Oganov (2019), Lyakhov-Oganov (2011).
+
+
+## AGAPI Agent
+
+```python
+from agapi.agents import AGAPIAgent
+import os
+agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
+response = agent.query_sync("Show hardmat data")
+print(response)
+```
+
+## References
+
+- V. Dovale-Farelo et al., Sci. Rep. 12, 22475 (2022) [:material-link: DOI](https://doi.org/10.1038/s41598-022-27083-w)
+- K. Choudhary, Comp. Mat. Sci. 259, 114063 (2025) [:material-link: DOI](https://doi.org/10.1016/j.commatsci.2025.114063)
+- [atomgptlab/jarvis](https://github.com/atomgptlab/jarvis)
diff --git a/docs/apps/explore/hea.md b/docs/apps/explore/hea.md
index ca468e8..97047b5 100644
--- a/docs/apps/explore/hea.md
+++ b/docs/apps/explore/hea.md
@@ -4,7 +4,7 @@ title: HEA Explorer
 
 # HEA Explorer
 
-High-Entropy Alloy design tool. Compute thermodynamic parameters (ΔS_mix, δ, VEC, Ω), predict phases (FCC/BCC/mixed), Hume-Rothery checks, and screen JARVIS-DFT for matching compositions.
+High-Entropy Alloy design tool. Two endpoints: (1) Compute — calculates thermodynamic parameters (ΔS_mix, atomic size mismatch δ, VEC, Ω parameter, ΔH_mix approximation) from element composition with equiatomic or custom fractions, predicts FCC/BCC phase and solid solution likelihood via Hume-Rothery rules. (2) Screen — searches JARVIS-DFT for multi-element compositions matching the target elements. Built-in database of 47 elements with atomic radii, melting points, VEC, electronegativity, density, and elastic modulus.
 
 [:material-open-in-new: Open App](https://atomgpt.org/hea){ .md-button .md-button--primary }
 
@@ -12,51 +12,78 @@ High-Entropy Alloy design tool. Compute thermodynamic parameters (ΔS_mix, δ, V
 
 ## Overview
 
-High-Entropy Alloy design tool. Compute thermodynamic parameters (ΔS_mix, δ, VEC, Ω), predict phases (FCC/BCC/mixed), Hume-Rothery checks, and screen JARVIS-DFT for matching compositions.
-
 !!! info "Data Source"
-    **dft_3d + built-in element property database**
+    **Built-in element property database** (47 elements) + **JARVIS dft_3d** (for composition screening).
 
 ## Endpoints
 
-- `GET /hea`
-- `POST /hea/compute`
-- `POST /hea/screen`
+### `POST /hea/compute` — Compute HEA parameters
 
-**Request Models:** `HEAComputeRequest`, `HEAScreenRequest`
+```bash
+curl -X POST "https://atomgpt.org/hea/compute" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -d '{"elements": ["Ti", "V", "Cr", "Mn", "Fe"]}'
+```
 
-!!! note "Authentication"
-    All POST endpoints require `Authorization: Bearer YOUR_TOKEN`.
+| Field | Type | Description |
+|-------|------|-------------|
+| `elements` | list[string] | 2–10 element symbols |
+| `fractions` | list[float] | Optional molar fractions (default: equiatomic) |
 
-## API Example
+**Response:** composition string, per-element properties, parameters (ΔS_mix, δ%, VEC, Ω, ΔH_mix, Tm_avg, ρ_avg, E_avg), predictions (FCC/BCC/mixed phase, solid solution likelihood, Hume-Rothery checks).
 
-```python
-import requests
-
-response = requests.post(
-    "https://atomgpt.org/hea/compute",
-    headers={
-        "Authorization": "Bearer sk-XYZ",
-        "accept": "application/json",
-        "Content-Type": "application/json",
-    },
-    json={"jid": "JVASP-1002"},
-)
-data = response.json()
-print(data)
+---
+
+### `POST /hea/screen` — Screen JARVIS-DFT
+
+```bash
+curl -X POST "https://atomgpt.org/hea/screen" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -d '{"elements": ["Ti", "V", "Cr"], "require_all": true, "max_results": 50}'
 ```
 
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `elements` | list[string] | required | Target elements |
+| `require_all` | bool | true | All elements must be present |
+| `min_elements` | int | 2 | Minimum number of elements |
+| `max_results` | int | 50 | Max results |
+
+
+---
+
+## Python Examples
+
+=== "Compute HEA"
+
+    ```python
+    import requests
+
+    response = requests.post(
+        "https://atomgpt.org/hea/compute",
+        headers={"Authorization": "Bearer sk-XYZ", "Content-Type": "application/json"},
+        json={"elements": ["Ti", "V", "Cr", "Mn", "Fe"]},
+    )
+    data = response.json()
+    p = data["parameters"]
+    print(f"{data['composition']}: VEC={p['VEC']}, δ={p['delta_pct']}%, ΔS={p['delta_s_mix_R']}R")
+    print(f"Phase: {data['predictions']['phase']}, SS likely: {data['predictions']['solid_solution_likely']}")
+    ```
+
+
 ## AGAPI Agent
 
 ```python
 from agapi.agents import AGAPIAgent
 import os
-
 agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
-response = agent.query_sync("Show hea explorer for Silicon")
+response = agent.query_sync("Show hea explorer data")
 print(response)
 ```
 
-## Reference
+## References
 
-- Mater. Today 19, 349 (2016)
+- Y. Zhang et al., Mater. Today 19, 349 (2016) [:material-link: DOI](https://doi.org/10.1016/j.mattod.2015.11.026)
+- [atomgptlab/jarvis](https://github.com/atomgptlab/jarvis)
diff --git a/docs/apps/explore/interface-db.md b/docs/apps/explore/interface-db.md
new file mode 100644
index 0000000..1fd718d
--- /dev/null
+++ b/docs/apps/explore/interface-db.md
@@ -0,0 +1,47 @@
+---
+title: Interface Database
+---
+
+# Interface Database
+
+Browse and search the JARVIS heterostructure interface database. View pre-computed interface properties including band alignments (Type I/II/III), lattice mismatch, and interface energies.
+
+[:material-open-in-new: Open App](https://atomgpt.org/interface_db){ .md-button .md-button--primary }
+
+---
+
+## Overview
+
+!!! info "Data Source"
+    **JARVIS interfacedb** — pre-computed heterostructure interface entries.
+
+## Endpoints
+
+### `GET /interface_db` — HTML page
+
+### `POST /interface_db/search` — Search interfaces
+
+```bash
+curl -X POST "https://atomgpt.org/interface_db/search" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -d '{"formula": "Si"}'
+```
+
+### `GET /interface_db/data/{idx}` — Full interface record
+
+
+## AGAPI Agent
+
+```python
+from agapi.agents import AGAPIAgent
+import os
+agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
+response = agent.query_sync("Show interface database data")
+print(response)
+```
+
+## References
+
+- K. Choudhary et al., Phys. Rev. Mat. 7, 014009 (2023) [:material-link: DOI](https://doi.org/10.1103/PhysRevMaterials.7.014009)
+- [atomgptlab/jarvis](https://github.com/atomgptlab/jarvis)
diff --git a/docs/apps/explore/interface.md b/docs/apps/explore/interface.md
index d4efd5a..c16400a 100644
--- a/docs/apps/explore/interface.md
+++ b/docs/apps/explore/interface.md
@@ -1,50 +1,73 @@
 ---
-title: Interface Explorer
+title: Interface Generator (API)
 ---
 
-# Interface Explorer
+# Interface Generator (API)
 
-Browse, search, and visualize heterostructure interface properties from the JARVIS interface database (607 entries). Band alignments and interface energies.
+Generate heterostructure interfaces via the REST API using InterfaceCombi (Zur & McGill ZSL lattice matching). This is the GET endpoint counterpart to the Heterostructure Builder's POST endpoint. Accepts film/substrate as POSCAR strings or JARVIS JIDs with full ZSL parameters. Optionally computes work of adhesion with ALIGNN-FF.
 
-[:material-open-in-new: Open App](https://atomgpt.org/interface_db){ .md-button .md-button--primary }
+[:material-open-in-new: Open App](https://atomgpt.org/generate_interface){ .md-button .md-button--primary }
 
 ---
 
 ## Overview
 
-Browse, search, and visualize heterostructure interface properties from the JARVIS interface database (607 entries). Band alignments and interface energies.
-
 !!! info "Data Source"
-    **interfacedb (607 entries)**
+    **InterMat** — `InterfaceCombi` for ZSL lattice matching. **JARVIS dft_3d** for JID lookups.
 
-## Endpoints
+## Endpoint
 
-- `GET /interface_db`
-- `POST /interface/search`
-- `GET /interface/data/{idx}`
+### `GET /generate_interface` — Generate heterostructure (API key)
 
-**Request Models:** `InterfaceSearchRequest`
+Returns the combined heterostructure POSCAR as plain text.
 
-!!! note "Authentication"
-    All POST endpoints require `Authorization: Bearer YOUR_TOKEN`.
+```bash
+curl "https://atomgpt.org/generate_interface?film_ids=JVASP-1002&subs_ids=JVASP-1174&film_indices=0_0_1&subs_indices=0_0_1&max_area=300&APIKEY=sk-XYZ"
+```
 
-## API Example
+| Param | Default | Description |
+|-------|---------|-------------|
+| `poscar_film` | null | Film POSCAR (provide this OR film_ids) |
+| `poscar_subs` | null | Substrate POSCAR (provide this OR subs_ids) |
+| `film_ids` | null | Comma-separated JARVIS JIDs for film |
+| `subs_ids` | null | Comma-separated JARVIS JIDs for substrate |
+| `film_indices` | 0_0_1 | Film Miller indices (h_k_l) |
+| `subs_indices` | 0_0_1 | Substrate Miller indices |
+| `film_thickness` | 16 | Film slab thickness (Å) |
+| `subs_thickness` | 16 | Substrate slab thickness (Å) |
+| `max_area` | 300 | Max supercell area (Ų) |
+| `ltol` | 0.08 | Length tolerance for ZSL |
+| `separations` | 2.5 | Comma-separated interface separations (Å) |
+| `vacuum_interface` | 2.0 | Vacuum at interface (Å) |
+| `conventional` | true | Use conventional cell |
+| `calculate_wad` | false | Compute W_ad with ALIGNN-FF |
+
+Returns plain text POSCAR of the heterostructure. With `calculate_wad=true`, returns JSON with `heterostructure_atoms`, `film_atoms`, `substrate_atoms`, `wads`, and `min_wad`.
 
-```python
-import requests
-
-response = requests.post(
-    "https://atomgpt.org/interface/search",
-    headers={
-        "Authorization": "Bearer sk-XYZ",
-        "accept": "application/json",
-        "Content-Type": "application/json",
-    },
-    json={"jid": "JVASP-1002"},
-)
-data = response.json()
-print(data)
-```
+---
+
+## Python Examples
+
+=== "Generate by JID"
+
+    ```python
+    import requests
+
+    response = requests.get(
+        "https://atomgpt.org/generate_interface",
+        params={
+            "film_ids": "JVASP-1002",
+            "subs_ids": "JVASP-1174",
+            "film_indices": "0_0_1",
+            "subs_indices": "0_0_1",
+            "max_area": 300,
+            "APIKEY": "sk-XYZ",
+        },
+    )
+    with open("POSCAR_interface", "w") as f:
+        f.write(response.text)
+    print(f"Interface POSCAR: {len(response.text)} chars")
+    ```
 
 ## AGAPI Agent
 
@@ -53,10 +76,12 @@ from agapi.agents import AGAPIAgent
 import os
 
 agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
-response = agent.query_sync("Show interface explorer for Silicon")
+response = agent.query_sync("Show interface generator (api) for Silicon")
 print(response)
 ```
 
-## Reference
+## References
 
-- Phys. Rev. Mat. 7, 014009 (2023)
+- K. Choudhary et al., Phys. Rev. Mat. 7, 014009 (2023) [:material-link: DOI](https://doi.org/10.1103/PhysRevMaterials.7.014009)
+- K. Choudhary et al., Digital Discovery 3, 1209 (2024) [:material-link: DOI](https://doi.org/10.1039/D4DD00031E)
+- [atomgptlab/jarvis](https://github.com/atomgptlab/jarvis)
diff --git a/docs/apps/explore/ir.md b/docs/apps/explore/ir.md
index 8952d85..02b0492 100644
--- a/docs/apps/explore/ir.md
+++ b/docs/apps/explore/ir.md
@@ -1,10 +1,10 @@
 ---
-title: IR Spectra
+title: IR Spectra Explorer
 ---
 
-# IR Spectra
+# IR Spectra Explorer
 
-Visualize and compare infrared spectra from JARVIS-DFT DFPT calculations. Born effective charges and phonon frequencies parsed from JARVIS XML.
+Visualize and compare infrared (IR) intensity spectra from JARVIS-DFT DFPT calculations. Returns raw peaks (frequency, intensity pairs) plus Gaussian-broadened spectra (σ=10 cm⁻¹, 500-point grid). Data parsed from JARVIS XML `<ir_intensity>` section.
 
 [:material-open-in-new: Open App](https://atomgpt.org/ir){ .md-button .md-button--primary }
 
@@ -12,40 +12,93 @@ Visualize and compare infrared spectra from JARVIS-DFT DFPT calculations. Born e
 
 ## Overview
 
-Visualize and compare infrared spectra from JARVIS-DFT DFPT calculations. Born effective charges and phonon frequencies parsed from JARVIS XML.
-
 !!! info "Data Source"
-    **dft_3d (DFPT, JARVIS XML)**
+    **JARVIS-DFT** — IR intensity from DFPT, parsed from JARVIS XML (`<ir_intensity>` tag).
 
 ## Endpoints
 
-- `GET /ir`
-- `POST /ir/search`
-- `GET /ir/data/{jid}`
+### `POST /ir/search` — Search materials
 
-**Request Models:** `IRSearchRequest`
+```bash
+curl -X POST "https://atomgpt.org/ir/search" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{"formula": "Si"}'
+```
 
-!!! note "Authentication"
-    All POST endpoints require `Authorization: Bearer YOUR_TOKEN`.
+Standard search fields: `formula`, `jid`, `elements`, `element_mode` (any/all/exact), `bandgap_min`, `bandgap_max`, `spacegroup`. Max 500 results.
 
-## API Example
+!!! note
+    Pre-filtered to materials with `max_ir_mode != 'na'`.
 
-```python
-import requests
-
-response = requests.post(
-    "https://atomgpt.org/ir/search",
-    headers={
-        "Authorization": "Bearer sk-XYZ",
-        "accept": "application/json",
-        "Content-Type": "application/json",
-    },
-    json={"jid": "JVASP-1002"},
-)
-data = response.json()
-print(data)
+---
+
+### `GET /ir/data/{jid}` — Fetch IR peaks and Gaussian-broadened spectrum.
+
+```bash
+curl "https://atomgpt.org/ir/data/JVASP-1002" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "accept: application/json"
 ```
 
+**Response:**
+
+```json
+{
+  "jid": "JVASP-5741",
+  "formula": "AlN",
+  "bandgap": 4.04,
+  "peaks": [{"frequency": 512.97, "intensity": 1.31}, {"frequency": 532.99, "intensity": 0.85}],
+  "gaussian_x": [480.0, 480.2, ...],
+  "gaussian_y": [0.0, 0.001, ...],
+  "max_ir_mode": 532.99,
+  "min_ir_mode": 512.97
+}
+```
+
+Raw peaks from XML `freq1,freq2,...;intensity1,intensity2,...` format. Gaussian broadening applied with σ=10 cm⁻¹ on a 500-point grid spanning ±5σ around the frequency range. Active modes are those with |intensity| > 1e-20.
+
+---
+
+## Python Examples
+
+=== "Search"
+
+    ```python
+    import requests
+
+    response = requests.post(
+        "https://atomgpt.org/ir/search",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={"formula": "Si"},
+    )
+    data = response.json()
+    print(f"Found {data['total']} entries")
+    for m in data["results"][:5]:
+        print(f"  {m['jid']}: {m.get('formula', m.get('bulk_formula', ''))}")
+    ```
+
+=== "Fetch data"
+
+    ```python
+    import requests
+
+    response = requests.get(
+        "https://atomgpt.org/ir/data/JVASP-1002",
+        headers={"Authorization": "Bearer sk-XYZ"},
+    )
+    data = response.json()
+    active = [p for p in data["peaks"] if abs(p["intensity"]) > 1e-10]
+    print(f"{data['formula']} — {len(active)} active IR modes")
+    for p in active[:5]:
+        print(f"  {p['frequency']:.1f} cm⁻¹: intensity={p['intensity']:.4f}")
+    ```
+
 ## AGAPI Agent
 
 ```python
@@ -53,10 +106,11 @@ from agapi.agents import AGAPIAgent
 import os
 
 agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
-response = agent.query_sync("Show ir spectra for Silicon")
+response = agent.query_sync("Show ir spectra explorer for Silicon")
 print(response)
 ```
 
-## Reference
+## References
 
-- NPJ Comp. Mat. 6, 1 (2020)
+- K. Choudhary et al., npj Comp. Mat. 6, 1 (2020) [:material-link: DOI](https://doi.org/10.1038/s41524-020-0337-2)
+- [atomgptlab/jarvis](https://github.com/atomgptlab/jarvis)
diff --git a/docs/apps/explore/literature.md b/docs/apps/explore/literature.md
new file mode 100644
index 0000000..bad9425
--- /dev/null
+++ b/docs/apps/explore/literature.md
@@ -0,0 +1,59 @@
+---
+title: Literature Explorer
+---
+
+# Literature Explorer
+
+Search for research papers and matching JARVIS materials simultaneously. Queries arXiv (full-text search) and Crossref (DOI-indexed publications) for papers, then cross-references the query formula against JARVIS-DFT for matching crystal structures. Also provides standalone GET endpoints for arXiv and Crossref API access.
+
+[:material-open-in-new: Open App](https://atomgpt.org/literature_materials){ .md-button .md-button--primary }
+
+---
+
+## Overview
+
+!!! info "Data Source"
+    **arXiv API** (Atom XML) + **Crossref API** (JSON) + **JARVIS dft_3d** (formula matching).
+
+## Endpoints
+
+### `POST /literature_materials/search` — Combined literature + materials search
+
+```bash
+curl -X POST "https://atomgpt.org/literature_materials/search" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -d '{"query": "MoS2", "max_papers": 10}'
+```
+
+**Response:** `papers.arxiv[]` (title, id, summary, published, authors), `papers.crossref[]` (title, doi, publisher, date), `materials[]` (jid, formula, spacegroup, band_gap, formation_energy).
+
+---
+
+### `GET /arxiv` — arXiv search (API key auth)
+
+```bash
+curl "https://atomgpt.org/arxiv?query=MgB2&max_results=10&APIKEY=sk-XYZ"
+```
+
+### `GET /crossref` — Crossref search (API key auth)
+
+```bash
+curl "https://atomgpt.org/crossref?query=Al2O3&rows=20&APIKEY=sk-XYZ"
+```
+
+
+## AGAPI Agent
+
+```python
+from agapi.agents import AGAPIAgent
+import os
+agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
+response = agent.query_sync("Show literature explorer data")
+print(response)
+```
+
+## References
+
+- K. Choudhary et al., npj Comp. Mat. 6, 173 (2020) [:material-link: DOI](https://doi.org/10.1038/s41524-020-00440-1)
+- [atomgptlab/jarvis](https://github.com/atomgptlab/jarvis)
diff --git a/docs/apps/explore/materials-explorer.md b/docs/apps/explore/materials-explorer.md
index a9a0af5..0187663 100644
--- a/docs/apps/explore/materials-explorer.md
+++ b/docs/apps/explore/materials-explorer.md
@@ -1,102 +1,144 @@
 ---
 title: Materials Explorer
-description: Search and explore 76K+ materials in JARVIS-DFT
-tags:
-  - explore
-  - database
-  - search
 ---
 
 # Materials Explorer
 
-Search and explore **76,000+ materials** in the JARVIS-DFT database. Filter by formula, elements, space group, band gap, formation energy, and 50+ properties.
+Search and explore **76,000+ materials** in JARVIS-DFT plus the Crystallography Open Database (COD). Filter by formula, elements (ANY/ALL/EXACT mode with periodic table selector), space group, and 19 property ranges across electronic, thermodynamic, mechanical, magnetic, optical, thermoelectric, and structural categories. Results are paginated, sortable, and exportable as CSV or JSON.
 
 [:material-open-in-new: Open App](https://atomgpt.org/materials_explorer){ .md-button .md-button--primary }
-[:material-github: Source](https://github.com/atomgptlab/jarvis){ .md-button }
 
 ---
 
 ## Overview
 
-The Materials Explorer provides full-text search across the JARVIS-DFT database with filters for chemical composition, crystal structure, electronic properties, and more. Each material links to its detailed JARVIS data page.
+The Materials Explorer provides advanced search across two databases: JARVIS-DFT (`dft_3d`, 76K+ materials with DFT-computed properties) and COD (experimental crystal structures). The JARVIS search supports 19 numeric property filters with min/max ranges, while COD supports formula, element, and space group filters. Results are capped at 1,000 entries per query.
 
 !!! info "Data Source"
-    **JARVIS-DFT** (`dft_3d`) — 76,000+ materials computed with OptB88vdW functional.
-    Updated from `jarvis.db.figshare.data('dft_3d')`.
-
-## Quick Start
-
-1. Enter a formula (e.g., `SrTiO3`) or elements (e.g., `Si, Ge`)
-2. Apply filters for band gap range, formation energy, or space group
-3. Click **Search** to find matching materials
-4. Click any result row to view detailed properties
-5. Click the JARVIS ID to open the full XML data page
-
-## Features
+    **JARVIS-DFT** — `dft_3d` via `jarvis.db.figshare.data('dft_3d')`, 76K+ materials with OptB88vdW properties.
+    **COD** — Crystallography Open Database, experimental structures.
+
+## Searchable Properties (JARVIS)
+
+| Category | Property | Key | Unit |
+|----------|----------|-----|------|
+| Electronic | MBJ Band Gap | `mbj_bandgap` | eV |
+| Electronic | OptB88vdW Band Gap | `optb88vdw_bandgap` | eV |
+| Electronic | HSE Band Gap | `hse_gap` | eV |
+| Electronic | Spillage | `spillage` | — |
+| Thermodynamic | Formation Energy | `formation_energy` | eV/atom |
+| Thermodynamic | Energy Above Hull | `ehull` | eV/atom |
+| Thermodynamic | Exfoliation Energy | `exfoliation_energy` | meV/atom |
+| Mechanical | Bulk Modulus | `bulk_modulus_kv` | GPa |
+| Mechanical | Shear Modulus | `shear_modulus_gv` | GPa |
+| Mechanical | Poisson Ratio | `poisson` | — |
+| Magnetic | Magnetic Moment | `magmom_oszicar` | μB |
+| Magnetic | Superconducting Tc | `Tc_supercon` | K |
+| Optical | SLME | `slme` | % |
+| Dielectric | Max Dielectric | `dfpt_piezo_max_dielectric` | — |
+| Thermoelectric | n-Seebeck | `n-Seebeck` | μV/K |
+| Thermoelectric | p-Seebeck | `p-Seebeck` | μV/K |
+| Structure | Density | `density` | g/cm³ |
+| Structure | Dimensionality | `dimensionality` | — |
+
+## Endpoints
+
+### `GET /materials_explorer/properties` — Property catalog
+
+Returns the list of all searchable properties with column names, labels, and units.
+
+```bash
+curl "https://atomgpt.org/materials_explorer/properties" \
+  -H "accept: application/json"
+```
 
-- **Search by formula**: Exact or partial formula matching
-- **Element filter**: ANY/ALL/EXACT mode with interactive periodic table
-- **Property filters**: Band gap, formation energy, bulk/shear modulus, magnetic moment, spillage, SLME, and more
-- **Results table**: Sortable by any property, paginated
-- **Detail view**: Full property card with JARVIS XML link
+---
 
-## API Reference
+### `POST /materials_explorer/search` — Search materials
 
-### Search Materials
+Search across JARVIS-DFT or COD with formula, element, space group, and property range filters.
 
-```
-POST /materials_explorer/search
+```bash
+curl -X POST "https://atomgpt.org/materials_explorer/search" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "database": "jarvis",
+    "formula": "SrTiO3"
+  }'
 ```
 
-**Request Body:**
+Search with element and property filters:
+
+```bash
+curl -X POST "https://atomgpt.org/materials_explorer/search" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "database": "jarvis",
+    "elements": ["Ti", "O"],
+    "element_mode": "all",
+    "property_filters": {
+      "optb88vdw_bandgap": {"min": 1.0, "max": 3.0},
+      "formation_energy": {"min": null, "max": 0.0}
+    },
+    "result_properties": ["optb88vdw_bandgap", "bulk_modulus_kv"]
+  }'
+```
 
-```json
-{
-  "jid": "JVASP-1002",
-  "formula": "Si",
-  "spacegroup": "Fd-3m",
-  "elements": ["Si", "Ge"],
-  "element_mode": "any",
-  "bandgap_min": 0.5,
-  "bandgap_max": 3.0,
-  "formation_energy_min": -2.0,
-  "formation_energy_max": 0.0
-}
+Search COD:
+
+```bash
+curl -X POST "https://atomgpt.org/materials_explorer/search" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "database": "cod",
+    "elements": ["Si", "O"],
+    "element_mode": "all"
+  }'
 ```
 
-**Response:**
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `database` | string | `"jarvis"` | `"jarvis"` or `"cod"` |
+| `formula` | string | null | Chemical formula (e.g. `"SrTiO3"`, `"MoS2"`) — auto-reduced |
+| `jid` | string | null | Exact JARVIS ID (e.g. `"JVASP-1002"`) or COD ID |
+| `spacegroup` | string | null | Space group symbol substring (e.g. `"Fm-3m"`) |
+| `elements` | list[string] | null | Element symbols (e.g. `["Ti", "O"]`) |
+| `element_mode` | string | `"any"` | `"any"` (contains any), `"all"` (contains all), `"exact"` (exactly these) |
+| `property_filters` | dict | null | Property range filters: `{"key": {"min": float, "max": float}}` |
+| `result_properties` | list[string] | null | Extra property keys to include in results beyond defaults |
+
+**Response (JARVIS):**
 
 ```json
 {
-  "total": 1234,
+  "database": "jarvis",
+  "total": 42,
   "results": [
     {
       "jid": "JVASP-1002",
       "formula": "Si",
-      "spg_symbol": "Fd-3m",
+      "spacegroup": "Fd-3m",
+      "mbj_bandgap": 1.156,
+      "formation_energy": -0.005,
+      "ehull": 0.0,
       "optb88vdw_bandgap": 0.611,
-      "formation_energy_peratom": -0.005,
-      "bulk_modulus_kv": 88.89,
-      "shear_modulus_gv": 51.47,
-      "magmom_oszicar": 0.0
+      "bulk_modulus_kv": 88.89
     }
   ]
 }
 ```
 
-!!! note "Authentication"
-    All POST endpoints require authentication. Include your token in the header:
-    ```
-    Authorization: Bearer YOUR_TOKEN
-    ```
-
-### Get Material Details
+Core fields always returned: `jid`, `formula`, `spacegroup`, `mbj_bandgap`, `formation_energy`, `ehull`. Additional properties appear when listed in `result_properties`.
 
-```
-GET /materials_explorer/detail/{jid}
-```
+**Response (COD):** `id`, `formula`, `spacegroup`, `authors`.
 
-Returns full property set for a single material.
+---
 
 ## Python Examples
 
@@ -108,19 +150,19 @@ Returns full property set for a single material.
     response = requests.post(
         "https://atomgpt.org/materials_explorer/search",
         headers={
-        "Authorization": "Bearer sk-XYZ",
-        "accept": "application/json",
-        "Content-Type": "application/json",
-    },
-        json={"formula": "SrTiO3"},
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={"database": "jarvis", "formula": "SrTiO3"},
     )
     data = response.json()
     print(f"Found {data['total']} materials")
     for m in data["results"][:5]:
-        print(f"  {m['jid']}: {m['formula']} gap={m['optb88vdw_bandgap']} eV")
+        print(f"  {m['jid']}: {m['formula']} gap={m['mbj_bandgap']} eV")
     ```
 
-=== "Search by elements"
+=== "Filter by elements + properties"
 
     ```python
     import requests
@@ -128,34 +170,49 @@ Returns full property set for a single material.
     response = requests.post(
         "https://atomgpt.org/materials_explorer/search",
         headers={
-        "Authorization": "Bearer sk-XYZ",
-        "accept": "application/json",
-        "Content-Type": "application/json",
-    },
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
         json={
+            "database": "jarvis",
             "elements": ["Ti", "O"],
             "element_mode": "all",
-            "bandgap_min": 1.0,
+            "property_filters": {
+                "optb88vdw_bandgap": {"min": 1.0, "max": 4.0},
+                "bulk_modulus_kv": {"min": 100, "max": None},
+            },
+            "result_properties": ["optb88vdw_bandgap", "bulk_modulus_kv"],
         },
     )
     data = response.json()
     for m in data["results"][:10]:
-        print(f"{m['jid']}: {m['formula']} ({m['spg_symbol']}) gap={m['optb88vdw_bandgap']}")
+        print(f"{m['jid']:12s} {m['formula']:10s} "
+              f"gap={m.get('optb88vdw_bandgap', 'N/A')} eV  "
+              f"Kv={m.get('bulk_modulus_kv', 'N/A')} GPa")
     ```
 
-=== "AGAPI Agent"
+=== "Search COD"
 
     ```python
-    from agapi import AtomGPTClient
+    import requests
 
-    client = AtomGPTClient(api_key="YOUR_KEY")
-    results = client.search_materials(
-        elements=["Si", "Ge"],
-        bandgap_min=0.5,
-        bandgap_max=2.0,
+    response = requests.post(
+        "https://atomgpt.org/materials_explorer/search",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={
+            "database": "cod",
+            "formula": "TiO2",
+        },
     )
-    for m in results:
-        print(m.formula, m.bandgap)
+    data = response.json()
+    print(f"COD: {data['total']} entries for TiO2")
+    for m in data["results"][:5]:
+        print(f"  COD-{m['id']}: {m['formula']} ({m['spacegroup']})")
     ```
 
 === "Direct JARVIS"
@@ -164,7 +221,6 @@ Returns full property set for a single material.
     from jarvis.db.figshare import data
 
     dft = data("dft_3d")
-    # Filter for Si-containing materials with gap > 1 eV
     results = [
         e for e in dft
         if "Si" in e.get("atoms", {}).get("elements", [])
@@ -174,15 +230,20 @@ Returns full property set for a single material.
     print(f"Found {len(results)} Si materials with gap > 1 eV")
     ```
 
-## Related Apps
+## AGAPI Agent
 
-- [Electronic DOS](electronic-dos.md) — View density of states for any material
-- [Elastic Tensor](elastic-tensor.md) — Explore mechanical properties
-- [Periodic Table](periodic-table.md) — Heatmap of properties across elements
-- [OPTIMADE Explorer](optimade.md) — Query using OPTIMADE standard syntax
+```python
+from agapi.agents import AGAPIAgent
+import os
+
+agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
+response = agent.query_sync("Find materials containing Ti and O with band gap > 2 eV")
+print(response)
+```
 
 ## References
 
-- K. Choudhary, Comp. Mat. Sci. 259, 114063 (2025). [:material-link: DOI](https://doi.org/10.1016/j.commatsci.2025.114063)
-- K. Choudhary et al., npj Comp. Mat. 6, 173 (2020). [:material-link: DOI](https://doi.org/10.1038/s41524-020-00440-1)
-- JARVIS-DFT Database: [jarvis.nist.gov](https://jarvis.nist.gov)
+- K. Choudhary, Comp. Mat. Sci. 259, 114063 (2025) [:material-link: DOI](https://doi.org/10.1016/j.commatsci.2025.114063)
+- K. Choudhary et al., npj Comp. Mat. 6, 173 (2020) [:material-link: DOI](https://doi.org/10.1038/s41524-020-00440-1)
+- [JARVIS-DFT Database](https://jarvis.nist.gov)
+- [atomgptlab/jarvis](https://github.com/atomgptlab/jarvis)
diff --git a/docs/apps/explore/meltmat.md b/docs/apps/explore/meltmat.md
new file mode 100644
index 0000000..dac3cb9
--- /dev/null
+++ b/docs/apps/explore/meltmat.md
@@ -0,0 +1,65 @@
+---
+title: MeltMat
+---
+
+# MeltMat
+
+Predict melting temperature (K) from elastic moduli using 5 models: Varshni/Gilvarry shear scaling, Vočadlo–Alfè empirical fit, Linear K (Stassis), Linear G power law, and Pugh-ratio-corrected Varshni. Also computes Debye temperature from sound velocities. Two tabs: JARVIS-DFT lookup and ALIGNN prediction from POSCAR.
+
+[:material-open-in-new: Open App](https://atomgpt.org/meltmat){ .md-button .md-button--primary }
+
+---
+
+## Overview
+
+!!! info "Data Source"
+    **JARVIS dft_3d** (Tab 1) + **ALIGNN** (Tab 2). Debye temperature from Voigt-averaged moduli.
+
+## Endpoints
+
+### `POST /meltmat/jarvis` — JARVIS-DFT lookup + predict Tm
+
+```bash
+curl -X POST "https://atomgpt.org/meltmat/jarvis" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -d '{"jid": "JVASP-1002"}'
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `jid` | string | JARVIS ID |
+| `formula` | string | Chemical formula (selects lowest-ehull entry with elastic data) |
+| `density_override` | float | Optional density override (g/cm³) |
+| `mass_override` | float | Optional average atomic mass override (amu) |
+
+**Response:** `jid, formula, K_GPa, G_GPa, density, avg_mass, vol_per_atom, theta_D` (Debye temp), `models` (5 Tm predictions in K), `spacegroup, ehull, bandgap`.
+
+---
+
+### `POST /meltmat/alignn` — ALIGNN prediction from POSCAR
+
+```bash
+curl -X POST "https://atomgpt.org/meltmat/alignn" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -d '{"poscar": "...", "density_override": null}'
+```
+
+**5 melting temperature models:** Varshni (Tm ∝ G·V^(1/3)), Vočadlo–Alfè (Tm ≈ 80·G^0.56), Linear K (354 + 4.5·K), Linear G (6.3·G^0.6), Pugh-corrected Varshni.
+
+
+## AGAPI Agent
+
+```python
+from agapi.agents import AGAPIAgent
+import os
+agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
+response = agent.query_sync("Show meltmat data")
+print(response)
+```
+
+## References
+
+- K. Choudhary, Comp. Mat. Sci. 259, 114063 (2025) [:material-link: DOI](https://doi.org/10.1016/j.commatsci.2025.114063)
+- [atomgptlab/jarvis](https://github.com/atomgptlab/jarvis)
diff --git a/docs/apps/explore/omim.md b/docs/apps/explore/omim.md
new file mode 100644
index 0000000..11acee6
--- /dev/null
+++ b/docs/apps/explore/omim.md
@@ -0,0 +1,64 @@
+---
+title: OMIM Gene Explorer
+---
+
+# OMIM Gene Explorer
+
+Browse the Online Mendelian Inheritance in Man (OMIM) database — 15,000+ genes and 8,000+ phenotypes. Three search modes: Gene Search (by symbol/keyword), Chromosome Browser (by chromosome position), and Clinical Synopsis Search (by phenotype features). Full entry detail with clinical synopsis, allelic variants, and text sections. Uses OMIM REST API.
+
+[:material-open-in-new: Open App](https://atomgpt.org/omim){ .md-button .md-button--primary }
+
+---
+
+## Overview
+
+!!! info "Data Source"
+    **OMIM REST API** (api.omim.org) — requires API key (configured server-side).
+
+## Endpoints
+
+### `POST /omim/gene_search` — Search genes/entries
+
+```bash
+curl -X POST "https://atomgpt.org/omim/gene_search" \
+  -H "Content-Type: application/json" \
+  -d '{"search": "BRCA1", "handler": "entry", "limit": 20}'
+```
+
+Also supports `preset` field: `brca_cancer, hemoglobin, collagen, ion_channel, metal_metabolism, kinase, crystallin, mitochondrial`.
+
+### `GET /omim/gene_search` — API key auth
+
+```bash
+curl "https://atomgpt.org/omim/gene_search?search=hemoglobin&APIKEY=sk-XYZ"
+```
+
+---
+
+### `POST /omim/entry` — Full entry by MIM number
+
+```bash
+curl -X POST "https://atomgpt.org/omim/entry" \
+  -H "Content-Type: application/json" \
+  -d '{"mimNumber": 113705}'
+```
+
+### `POST /omim/genemap` — Browse by chromosome
+
+### `POST /omim/clinical_search` — Clinical synopsis search
+
+
+## AGAPI Agent
+
+```python
+from agapi.agents import AGAPIAgent
+import os
+agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
+response = agent.query_sync("Show omim gene explorer data")
+print(response)
+```
+
+## References
+
+- OMIM — Online Mendelian Inheritance in Man [:material-link: DOI](https://omim.org)
+- [atomgptlab/jarvis](https://github.com/atomgptlab/jarvis)
diff --git a/docs/apps/explore/optimade.md b/docs/apps/explore/optimade.md
index da604cb..f571824 100644
--- a/docs/apps/explore/optimade.md
+++ b/docs/apps/explore/optimade.md
@@ -4,7 +4,7 @@ title: OPTIMADE Explorer
 
 # OPTIMADE Explorer
 
-Query JARVIS-DFT using OPTIMADE-style filters served directly from the dft_3d dataset (no external API calls). Supports elements HAS ANY/ALL/ONLY, formula, nelements, nsites, and numeric property filters.
+Query JARVIS-DFT using OPTIMADE-style filter syntax served from an in-memory engine (no external API calls). Supports: `elements HAS ANY/ALL/ONLY`, `chemical_formula_reduced`, `chemical_formula_anonymous`, `spg_symbol`, `id`, and numeric comparisons (>=, <=, >, <, =, !=) on 11 properties. Paginated results in OPTIMADE v1.1.0 format with lattice vectors and site positions.
 
 [:material-open-in-new: Open App](https://atomgpt.org/optimade_explorer){ .md-button .md-button--primary }
 
@@ -12,51 +12,67 @@ Query JARVIS-DFT using OPTIMADE-style filters served directly from the dft_3d da
 
 ## Overview
 
-Query JARVIS-DFT using OPTIMADE-style filters served directly from the dft_3d dataset (no external API calls). Supports elements HAS ANY/ALL/ONLY, formula, nelements, nsites, and numeric property filters.
-
 !!! info "Data Source"
-    **dft_3d (in-memory OPTIMADE filter engine)**
+    **JARVIS dft_3d** — in-memory OPTIMADE filter engine over 76K+ entries.
 
 ## Endpoints
 
-- `GET /optimade_explorer`
-- `POST /optimade_explorer/query`
-- `GET /optimade_explorer/entry/{jid}`
+### `POST /optimade_explorer/query` — OPTIMADE filter query
 
-**Request Models:** `OptimadeQueryRequest`
+```bash
+curl -X POST "https://atomgpt.org/optimade_explorer/query" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -d '{"filter_string": "elements HAS ALL \\"Si\\",\\"O\\" AND optb88vdw_bandgap > 2", "page": 1, "page_size": 25}'
+```
 
-!!! note "Authentication"
-    All POST endpoints require `Authorization: Bearer YOUR_TOKEN`.
+**Supported filters:** `elements HAS ANY/ALL/ONLY "El"`, `chemical_formula_reduced = "X"`, `chemical_formula_anonymous = "AB2"`, `spg_symbol`, `id`, and numeric `>=/<=/>/</=/!=` on: nelements, nsites, formation_energy_peratom, optb88vdw_bandgap, mbj_bandgap, ehull, bulk_modulus_kv, shear_modulus_gv, spillage, magmom_oszicar, slme, density. Clauses joined with `AND`.
 
-## API Example
+**Response:** OPTIMADE v1.1.0 format with `meta`, `links` (pagination), `data` (id, type, attributes with lattice_vectors, cartesian_site_positions, species_at_sites, and all numeric properties).
 
-```python
-import requests
-
-response = requests.post(
-    "https://atomgpt.org/optimade_explorer/query",
-    headers={
-        "Authorization": "Bearer sk-XYZ",
-        "accept": "application/json",
-        "Content-Type": "application/json",
-    },
-    json={"jid": "JVASP-1002"},
-)
-data = response.json()
-print(data)
+---
+
+### `GET /optimade_explorer/entry/{jid}` — Single entry
+
+```bash
+curl "https://atomgpt.org/optimade_explorer/entry/JVASP-1002" \
+  -H "Authorization: Bearer sk-XYZ"
 ```
 
+
+---
+
+## Python Examples
+
+=== "OPTIMADE query"
+
+    ```python
+    import requests
+
+    response = requests.post(
+        "https://atomgpt.org/optimade_explorer/query",
+        headers={"Authorization": "Bearer sk-XYZ", "Content-Type": "application/json"},
+        json={"filter_string": "elements HAS ALL \"Si\",\"O\" AND optb88vdw_bandgap > 3", "page_size": 10},
+    )
+    data = response.json()
+    print(f"Found {data['total']} materials")
+    for entry in data["data"]:
+        a = entry["attributes"]
+        print(f"  {entry['id']}: {a['chemical_formula_reduced']} gap={a['optb88vdw_bandgap']}")
+    ```
+
+
 ## AGAPI Agent
 
 ```python
 from agapi.agents import AGAPIAgent
 import os
-
 agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
-response = agent.query_sync("Show optimade explorer for Silicon")
+response = agent.query_sync("Show optimade explorer data")
 print(response)
 ```
 
-## Reference
+## References
 
-- NPJ Comp. Mat. 6, 173 (2020)
+- K. Choudhary et al., npj Comp. Mat. 6, 173 (2020) [:material-link: DOI](https://doi.org/10.1038/s41524-020-00440-1)
+- [atomgptlab/jarvis](https://github.com/atomgptlab/jarvis)
diff --git a/docs/apps/explore/pdb-explorer.md b/docs/apps/explore/pdb-explorer.md
index 6210e06..de36ad7 100644
--- a/docs/apps/explore/pdb-explorer.md
+++ b/docs/apps/explore/pdb-explorer.md
@@ -4,7 +4,7 @@ title: PDB Explorer
 
 # PDB Explorer
 
-Search 200K+ protein structures from RCSB PDB. 3D Mol* viewer (RCSB embed iframe), sequence display with position markers, unit cell and crystallographic data, polymer entities. Uses RCSB REST API (no key needed).
+Search 200K+ protein structures from the RCSB Protein Data Bank. Full-text search via RCSB Search API v2, with detailed entry metadata (resolution, R-factor, authors, unit cell, polymer entities with sequences). No API key needed — the app proxies RCSB REST API calls.
 
 [:material-open-in-new: Open App](https://atomgpt.org/pdb_explorer){ .md-button .md-button--primary }
 
@@ -12,51 +12,71 @@ Search 200K+ protein structures from RCSB PDB. 3D Mol* viewer (RCSB embed iframe
 
 ## Overview
 
-Search 200K+ protein structures from RCSB PDB. 3D Mol* viewer (RCSB embed iframe), sequence display with position markers, unit cell and crystallographic data, polymer entities. Uses RCSB REST API (no key needed).
-
 !!! info "Data Source"
-    **RCSB PDB REST API**
+    **RCSB PDB REST API** — `search.rcsb.org` (search) + `data.rcsb.org` (entry metadata + polymer entities).
 
 ## Endpoints
 
-- `GET /pdb_explorer`
-- `POST /pdb_explorer/search`
-- `GET /pdb_explorer/entry/{pdb_id}`
+### `POST /pdb_explorer/search` — Search materials
 
-**Request Models:** `PDBSearchRequest`
+```bash
+curl -X POST "https://atomgpt.org/pdb_explorer/search" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -d '{"formula": "MoS2"}'
+```
 
-!!! note "Authentication"
-    All POST endpoints require `Authorization: Bearer YOUR_TOKEN`.
+| Field | Type | Description |
+|-------|------|-------------|
+| `query` | string | Full-text search query (e.g. 'insulin', 'kinase') |
+| `max_results` | int | Max results (default 20, max 50) |
 
-## API Example
+**Response:** `pdb_id, score, title, method, resolution, deposition_date, organism, authors, spacegroup`.
 
-```python
-import requests
-
-response = requests.post(
-    "https://atomgpt.org/pdb_explorer/search",
-    headers={
-        "Authorization": "Bearer sk-XYZ",
-        "accept": "application/json",
-        "Content-Type": "application/json",
-    },
-    json={"jid": "JVASP-1002"},
-)
-data = response.json()
-print(data)
+---
+
+### `GET /pdb_explorer/data/{jid}` — Full record
+
+```bash
+curl "https://atomgpt.org/pdb_explorer/data/JVASP-664" \
+  -H "Authorization: Bearer sk-XYZ"
 ```
 
+**Response:** pdb_id, title, method, resolution, r_factor, r_free, deposition/release dates, authors, journal, doi, pub_year, cell (a/b/c/α/β/γ), spacegroup, z_value, polymer/nonpolymer/assembly counts, molecular_weight, polymers (entity_id, name, type, sequence, length, organism, weight).
+
+
+---
+
+## Python Examples
+
+=== "Fetch data"
+
+    ```python
+    import requests
+
+    response = requests.get(
+        "https://atomgpt.org/pdb_explorer/data/JVASP-1002",
+        headers={"Authorization": "Bearer sk-XYZ"},
+    )
+    data = response.json()
+    print(f"{data['pdb_id']}: {data['title']}")
+    print(f"  Method: {data['method']}, Resolution: {data['resolution']} Å")
+    for p in data["polymers"]:
+        print(f"  Chain {p['entity_id']}: {p['name']} ({p['length']} residues)")
+    ```
+
+
 ## AGAPI Agent
 
 ```python
 from agapi.agents import AGAPIAgent
 import os
-
 agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
-response = agent.query_sync("Show pdb explorer for Silicon")
+response = agent.query_sync("Show pdb explorer data")
 print(response)
 ```
 
-## Reference
+## References
 
-- Nucleic Acids Res. 28, 235 (2000)
+- H.M. Berman et al., Nucleic Acids Res. 28, 235 (2000) [:material-link: DOI](https://doi.org/10.1093/nar/28.1.235)
+- [atomgptlab/jarvis](https://github.com/atomgptlab/jarvis)
diff --git a/docs/apps/explore/periodic-table.md b/docs/apps/explore/periodic-table.md
index 7d5b797..1fd7e4c 100644
--- a/docs/apps/explore/periodic-table.md
+++ b/docs/apps/explore/periodic-table.md
@@ -4,7 +4,7 @@ title: Periodic Table
 
 # Periodic Table
 
-Interactive periodic table with JARVIS property overlays. Backend provides per-element property statistics aggregated from JARVIS-DFT 3D (76K materials). Fully client-side visualization.
+Interactive periodic table with JARVIS property overlays. The backend aggregates per-element statistics from all 76K+ materials in dft_3d, computing count, mean, min, max, and median for 40+ properties including band gaps, formation energy, mechanical moduli, dielectric constants, thermoelectric coefficients, and more.
 
 [:material-open-in-new: Open App](https://atomgpt.org/periodic_table){ .md-button .md-button--primary }
 
@@ -12,48 +12,56 @@ Interactive periodic table with JARVIS property overlays. Backend provides per-e
 
 ## Overview
 
-Interactive periodic table with JARVIS property overlays. Backend provides per-element property statistics aggregated from JARVIS-DFT 3D (76K materials). Fully client-side visualization.
-
 !!! info "Data Source"
-    **dft_3d (aggregated per-element stats)**
+    **JARVIS dft_3d** — per-element statistics aggregated from 76K+ materials.
 
 ## Endpoints
 
-- `GET /periodic_table`
-- `GET /periodic_table/stats`
+### `GET /periodic_table/stats` — Per-element aggregated statistics
 
-**Request Models:** —
+```bash
+curl "https://atomgpt.org/periodic_table/stats" \
+  -H "Authorization: Bearer sk-XYZ"
+```
 
-!!! note "Authentication"
-    All POST endpoints require `Authorization: Bearer YOUR_TOKEN`.
+**Response:** Per-element dict: `{count, bandgap: {n, mean, min, max, median}, formation_energy: {...}, bulk_modulus: {...}, ...}` for 40+ properties.
 
-## API Example
+40+ properties aggregated: bandgap, mbj_bandgap, hse_gap, spillage, formation_energy, ehull, exfoliation_energy, magmom, bulk_modulus, shear_modulus, poisson, epsx/y/z, mepsx/y/z, piezo_eij/dij, max_ir_mode, n/p-Seebeck, slme, max_efg, avg_elec/hole_mass, Tc_supercon, density, and more.
+
+
+---
+
+## Python Examples
+
+=== "Fetch data"
+
+    ```python
+    import requests
+
+    response = requests.get(
+        "https://atomgpt.org/periodic_table/data/JVASP-1002",
+        headers={"Authorization": "Bearer sk-XYZ"},
+    )
+    data = response.json()
+    si = data.get("Si", {})
+    print(f"Si: {si['count']} materials in JARVIS")
+    bg = si.get("bandgap")
+    if bg:
+        print(f"  Band gap: mean={bg['mean']}, range=[{bg['min']}, {bg['max']}] eV")
+    ```
 
-```python
-import requests
-
-response = requests.get(
-    "https://atomgpt.org/periodic_table/stats",
-    headers={
-        "Authorization": "Bearer sk-XYZ",
-        "accept": "application/json",
-    },
-)
-data = response.json()
-print(data)
-```
 
 ## AGAPI Agent
 
 ```python
 from agapi.agents import AGAPIAgent
 import os
-
 agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
-response = agent.query_sync("Show periodic table for Silicon")
+response = agent.query_sync("Show periodic table data")
 print(response)
 ```
 
-## Reference
+## References
 
-- Comp. Mat. Sci. 259, 114063 (2025)
+- K. Choudhary, Comp. Mat. Sci. 259, 114063 (2025) [:material-link: DOI](https://doi.org/10.1016/j.commatsci.2025.114063)
+- [atomgptlab/jarvis](https://github.com/atomgptlab/jarvis)
diff --git a/docs/apps/explore/phonon-dos.md b/docs/apps/explore/phonon-dos.md
index 50cff8d..2122195 100644
--- a/docs/apps/explore/phonon-dos.md
+++ b/docs/apps/explore/phonon-dos.md
@@ -4,7 +4,7 @@ title: Phonon DOS
 
 # Phonon DOS
 
-Visualize and compare phonon density of states from JARVIS-DFT. Vibrational spectra fetched from JARVIS XML pages.
+Visualize and compare phonon density of states from JARVIS-DFT. Vibrational spectra fetched from JARVIS XML pages via `Webpage.get_dft_phonon_dos()`. Includes filtering of non-DOS keys (elastic properties, metadata) that leak from the XML parser.
 
 [:material-open-in-new: Open App](https://atomgpt.org/phonon_dos){ .md-button .md-button--primary }
 
@@ -12,40 +12,119 @@ Visualize and compare phonon density of states from JARVIS-DFT. Vibrational spec
 
 ## Overview
 
-Visualize and compare phonon density of states from JARVIS-DFT. Vibrational spectra fetched from JARVIS XML pages.
+Search materials by formula, JARVIS ID, elements, space group, or property ranges. Click any result to fetch and plot the full spectrum. All search results are capped at 500 entries.
 
 !!! info "Data Source"
-    **dft_3d (JARVIS XML)**
+    **JARVIS-DFT** — phonon DOS fetched via `jarvis.db.webpages.Webpage.get_dft_phonon_dos()`.
 
 ## Endpoints
 
-- `GET /phonon_dos`
-- `POST /phonon_dos/search`
-- `GET /phonon_dos/data/{jid}`
+### `POST /phonon_dos/search` — Search materials
 
-**Request Models:** `PhononDOSSearchRequest`
+```bash
+curl -X POST "https://atomgpt.org/phonon_dos/search" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "formula": "Si"
+  }'
+```
+
+Search with elements:
+
+```bash
+curl -X POST "https://atomgpt.org/phonon_dos/search" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "elements": ["Ti", "O"],
+    "element_mode": "all"
+  }'
+```
 
-!!! note "Authentication"
-    All POST endpoints require `Authorization: Bearer YOUR_TOKEN`.
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `formula` | string | null | Chemical formula |
+| `jid` | string | null | Exact JARVIS ID |
+| `elements` | list[string] | null | Element symbols |
+| `element_mode` | string | "any" | "any", "all", or "exact" |
+| `bandgap_min` | float | null | Min OptB88vdW band gap (eV) |
+| `bandgap_max` | float | null | Max OptB88vdW band gap (eV) |
+| `spacegroup` | string | null | Space group substring |
 
-## API Example
+**Response fields:** `jid, formula, spacegroup, optb88vdw_bandgap, mbj_bandgap, magmom`.
 
-```python
-import requests
-
-response = requests.post(
-    "https://atomgpt.org/phonon_dos/search",
-    headers={
-        "Authorization": "Bearer sk-XYZ",
-        "accept": "application/json",
-        "Content-Type": "application/json",
-    },
-    json={"jid": "JVASP-1002"},
-)
-data = response.json()
-print(data)
+!!! note
+    Pre-filtered to materials with `bulk_modulus_kv != 'na'` (materials with mechanical data tend to have phonon DOS).
+
+---
+
+### `GET /phonon_dos/data/{jid}` — Fetch spectrum data
+
+Fetch phonon DOS spectrum for a single material. Returns frequency axis and DOS channels.
+
+```bash
+curl "https://atomgpt.org/phonon_dos/data/JVASP-1002" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "accept: application/json"
+```
+
+**Response:**
+
+```json
+{
+  "jid": "JVASP-1002",
+  "formula": "Si",
+  "bandgap": 0.611,
+  "frequencies": [0.0, 0.5, 1.0, ...],
+  "components": {
+    "Total": [0.0, 0.12, 0.35, ...]
+  }
+}
 ```
 
+Frequency axis searched across keys: `frequencies`, `frequency`, `phonon_dos_frequencies`, `omega`. Non-DOS keys (elastic constants, metadata scalars) are filtered out. Only arrays matching the frequency axis length are included as channels.
+
+---
+
+## Python Examples
+
+=== "Search"
+
+    ```python
+    import requests
+
+    response = requests.post(
+        "https://atomgpt.org/phonon_dos/search",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={"formula": "Si"},
+    )
+    data = response.json()
+    print(f"Found {data['total']} materials")
+    for m in data["results"][:5]:
+        print(f"  {m['jid']}: {m['formula']}")
+    ```
+
+=== "Fetch data"
+
+    ```python
+    import requests
+
+    response = requests.get(
+        "https://atomgpt.org/phonon_dos/data/JVASP-1002",
+        headers={"Authorization": "Bearer sk-XYZ"},
+    )
+    data = response.json()
+    print(f"{data['formula']} — {len(data['frequencies'])} frequency points")
+    print(f"Max frequency: {max(data['frequencies']):.1f} THz")
+    ```
+
 ## AGAPI Agent
 
 ```python
@@ -57,6 +136,7 @@ response = agent.query_sync("Show phonon dos for Silicon")
 print(response)
 ```
 
-## Reference
+## References
 
-- Phys. Rev. Mat. 7, 023803 (2023)
+- K. Choudhary et al., Phys. Rev. Mat. 7, 023803 (2023) [:material-link: DOI](https://doi.org/10.1103/PhysRevMaterials.7.023803)
+- [atomgptlab/jarvis](https://github.com/atomgptlab/jarvis)
diff --git a/docs/apps/explore/piezoelectric.md b/docs/apps/explore/piezoelectric.md
index 30af31d..26efaf0 100644
--- a/docs/apps/explore/piezoelectric.md
+++ b/docs/apps/explore/piezoelectric.md
@@ -1,10 +1,10 @@
 ---
-title: Piezoelectric
+title: Piezoelectric Explorer
 ---
 
-# Piezoelectric
+# Piezoelectric Explorer
 
-Visualize and compare DFPT piezoelectric stress tensors eij (C/m²) and IR intensities from JARVIS-DFT calculations.
+Visualize and compare DFPT piezoelectric stress tensors eij (3×6 Voigt, C/m²) and IR intensity spectra from JARVIS-DFT. Data parsed from JARVIS XML `<dfpt_piezoelectric_tensor>` and `<ir_intensity>` sections.
 
 [:material-open-in-new: Open App](https://atomgpt.org/piezoelectric){ .md-button .md-button--primary }
 
@@ -12,40 +12,96 @@ Visualize and compare DFPT piezoelectric stress tensors eij (C/m²) and IR inten
 
 ## Overview
 
-Visualize and compare DFPT piezoelectric stress tensors eij (C/m²) and IR intensities from JARVIS-DFT calculations.
-
 !!! info "Data Source"
-    **dft_3d (DFPT)**
+    **JARVIS-DFT** — DFPT piezoelectric tensor and IR intensity from JARVIS XML.
 
 ## Endpoints
 
-- `GET /piezoelectric`
-- `POST /piezoelectric/search`
-- `GET /piezoelectric/data/{jid}`
+### `POST /piezoelectric/search` — Search materials
 
-**Request Models:** `PiezoSearchRequest`
+```bash
+curl -X POST "https://atomgpt.org/piezoelectric/search" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{"formula": "Si"}'
+```
 
-!!! note "Authentication"
-    All POST endpoints require `Authorization: Bearer YOUR_TOKEN`.
+Standard search fields: `formula`, `jid`, `elements`, `element_mode` (any/all/exact), `bandgap_min`, `bandgap_max`, `spacegroup`. Max 500 results.
 
-## API Example
+!!! note
+    Pre-filtered to materials with `dfpt_piezo_max_eij != 'na'`.
 
-```python
-import requests
-
-response = requests.post(
-    "https://atomgpt.org/piezoelectric/search",
-    headers={
-        "Authorization": "Bearer sk-XYZ",
-        "accept": "application/json",
-        "Content-Type": "application/json",
-    },
-    json={"jid": "JVASP-1002"},
-)
-data = response.json()
-print(data)
+---
+
+### `GET /piezoelectric/data/{jid}` — Fetch 3×6 piezoelectric stress tensor and IR intensity spectrum.
+
+```bash
+curl "https://atomgpt.org/piezoelectric/data/JVASP-1002" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "accept: application/json"
 ```
 
+**Response:**
+
+```json
+{
+  "jid": "JVASP-5741",
+  "formula": "AlN",
+  "bandgap": 4.04,
+  "max_piezo": 1.04,
+  "piezo_tensor": [[e11,e12,e13,e14,e15,e16], [e21,...], [e31,...]],
+  "ir": {"frequencies": [512.97, 532.99, ...], "intensities": [1.31, 0.85, ...]},
+  "max_ir_mode": 532.99,
+  "min_ir_mode": 512.97
+}
+```
+
+Piezo tensor is 3×6 (3 Cartesian directions × 6 Voigt strain components). XML format: 6 columns separated by commas, each column has 3 rows separated by semicolons. IR format: `freq1,freq2,...;intensity1,intensity2,...`. Returns both tensor and IR when available.
+
+---
+
+## Python Examples
+
+=== "Search"
+
+    ```python
+    import requests
+
+    response = requests.post(
+        "https://atomgpt.org/piezoelectric/search",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={"formula": "Si"},
+    )
+    data = response.json()
+    print(f"Found {data['total']} entries")
+    for m in data["results"][:5]:
+        print(f"  {m['jid']}: {m.get('formula', m.get('bulk_formula', ''))}")
+    ```
+
+=== "Fetch data"
+
+    ```python
+    import requests
+
+    response = requests.get(
+        "https://atomgpt.org/piezoelectric/data/JVASP-1002",
+        headers={"Authorization": "Bearer sk-XYZ"},
+    )
+    data = response.json()
+    print(f"{data['formula']} — max piezo: {data['max_piezo']} C/m²")
+    if data["piezo_tensor"]:
+        import numpy as np
+        t = np.array(data["piezo_tensor"])
+        print(f"  Tensor shape: {t.shape}, max |eij|: {np.abs(t).max():.3f}")
+    if data["ir"]:
+        print(f"  IR modes: {len(data['ir']['frequencies'])}")
+    ```
+
 ## AGAPI Agent
 
 ```python
@@ -53,10 +109,11 @@ from agapi.agents import AGAPIAgent
 import os
 
 agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
-response = agent.query_sync("Show piezoelectric for Silicon")
+response = agent.query_sync("Show piezoelectric explorer for Silicon")
 print(response)
 ```
 
-## Reference
+## References
 
-- NPJ Comp. Mat. 6, 1 (2020)
+- K. Choudhary et al., npj Comp. Mat. 6, 1 (2020) [:material-link: DOI](https://doi.org/10.1038/s41524-020-0337-2)
+- [atomgptlab/jarvis](https://github.com/atomgptlab/jarvis)
diff --git a/docs/apps/explore/polymer-builder.md b/docs/apps/explore/polymer-builder.md
new file mode 100644
index 0000000..1cf4cb9
--- /dev/null
+++ b/docs/apps/explore/polymer-builder.md
@@ -0,0 +1,68 @@
+---
+title: Polymer Chain Builder
+---
+
+# Polymer Chain Builder
+
+Build statistical polymer chains using 4 models: FJC (Freely Jointed Chain with optional angle constraint), FRC (Freely Rotating Chain), WLC (Worm-Like Chain), and RIS (Rotational Isomeric State). Computes chain statistics (Ree, Rg, C∞, persistence length, overlap concentration), supports monomer XYZ upload for full-atom visualization, batch sampling for distributions, and bulk periodic box generation with LAMMPS topology export. Adapted from polybuildv4.f (K. Choudhary, JHU/NIST).
+
+[:material-open-in-new: Open App](https://atomgpt.org/polymer_builder){ .md-button .md-button--primary }
+
+---
+
+## Overview
+
+!!! info "Data Source"
+    Client-side 3D visualization + server-side chain generation. No external databases.
+
+## Endpoints
+
+### `POST /polymer_builder/generate` — Generate single chain
+
+```bash
+curl -X POST "https://atomgpt.org/polymer_builder/generate" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -F "model=FJC" -F "N=100" -F "b=1.5" -F "seed=42"
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `model` | string | FJC | Chain model: FJC, FRC, WLC, RIS |
+| `N` | int | 100 | Chain length (monomers) |
+| `b` | float | 1.5 | Bond length (Å) |
+| `theta` | float | 109.5 | Bond angle (°, FRC/RIS) |
+| `Lp` | float | 10.0 | Persistence length (Å, WLC) |
+| `T` | float | 300.0 | Temperature (K, RIS) |
+| `seed` | int | 42 | Random seed |
+| `cos_min` | float | -1.0 | Angle constraint for FJC (-1=off) |
+| `mw_monomer` | float | 0 | Monomer molecular weight (g/mol) |
+| `xyz_string` | string | null | Monomer XYZ (optional) |
+
+**Response:** `pts` (backbone coordinates), `stats` (Ree, Rg, L, C_inf, Lp_eff, c_star_mg_mL, bulk_density), `mono` info.
+
+---
+
+### `POST /polymer_builder/sample` — Batch sample distributions
+
+Returns Ree/Rg arrays for up to 500 chains.
+
+### `POST /polymer_builder/export` — Export chain (XYZ/PDB/ZIP/LAMMPS)
+
+### `POST /polymer_builder/bulk` — Build periodic bulk box (up to 200 chains, LAMMPS topology)
+
+
+## AGAPI Agent
+
+```python
+from agapi.agents import AGAPIAgent
+import os
+agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
+response = agent.query_sync("Show polymer chain builder data")
+print(response)
+```
+
+## References
+
+- P.J. Flory, Statistical Mechanics of Chain Molecules (1969) [:material-link: DOI](https://doi.org/10.1002/9780470316566)
+- K. Choudhary et al., npj Comp. Mat. 6, 173 (2020) [:material-link: DOI](https://doi.org/10.1038/s41524-020-00440-1)
+- [atomgptlab/jarvis](https://github.com/atomgptlab/jarvis)
diff --git a/docs/apps/explore/polymer.md b/docs/apps/explore/polymer.md
index abd4e47..8f0ed58 100644
--- a/docs/apps/explore/polymer.md
+++ b/docs/apps/explore/polymer.md
@@ -4,7 +4,7 @@ title: Polymer Explorer
 
 # Polymer Explorer
 
-Browse, search, and visualize crystalline polymer properties by cross-referencing Polymer Genome database (1073 entries) with JARVIS-DFT. Dielectrics, band gaps, formation energies.
+Browse and search crystalline polymer properties by cross-referencing the Polymer Genome database (1,073 entries) with JARVIS-DFT 3D via the `reference` field. Merges DFT-computed properties (band gaps, mechanical, magnetic) with polymer-specific data (HSE/GGA gaps, dielectric constants from Polymer Genome).
 
 [:material-open-in-new: Open App](https://atomgpt.org/polymer){ .md-button .md-button--primary }
 
@@ -12,51 +12,74 @@ Browse, search, and visualize crystalline polymer properties by cross-referencin
 
 ## Overview
 
-Browse, search, and visualize crystalline polymer properties by cross-referencing Polymer Genome database (1073 entries) with JARVIS-DFT. Dielectrics, band gaps, formation energies.
-
 !!! info "Data Source"
-    **polymer_genome (1073 entries) + dft_3d**
+    **Polymer Genome** (1,073 entries) cross-referenced with **JARVIS dft_3d** (76K entries) via `reference` field.
 
 ## Endpoints
 
-- `GET /polymer`
-- `POST /polymer/search`
-- `GET /polymer/data/{jid}`
+### `POST /polymer/search` — Search materials
 
-**Request Models:** `PolymerSearchRequest`
+```bash
+curl -X POST "https://atomgpt.org/polymer/search" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -d '{"formula": "MoS2"}'
+```
 
-!!! note "Authentication"
-    All POST endpoints require `Authorization: Bearer YOUR_TOKEN`.
+| Field | Type | Description |
+|-------|------|-------------|
+| `formula` | string | Chemical formula |
+| `jid` | string | JARVIS ID |
+| `label` | string | Polymer label substring |
+| `elements` | string | Comma-separated elements (all required) |
+| `bandgap_min/max` | float | OptB88vdW band gap range (eV) |
+| `diel_min/max` | float | Total dielectric constant range |
 
-## API Example
+**Response:** `jid, poly_id, formula, label, spg_symbol, bandgap, hse_gap_pg, gga_gap_pg, diel_tot, diel_elec, formation_energy, magmom`.
 
-```python
-import requests
-
-response = requests.post(
-    "https://atomgpt.org/polymer/search",
-    headers={
-        "Authorization": "Bearer sk-XYZ",
-        "accept": "application/json",
-        "Content-Type": "application/json",
-    },
-    json={"jid": "JVASP-1002"},
-)
-data = response.json()
-print(data)
+---
+
+### `GET /polymer/data/{jid}` — Full record
+
+```bash
+curl "https://atomgpt.org/polymer/data/JVASP-664" \
+  -H "Authorization: Bearer sk-XYZ"
 ```
 
+**Response:** Merged fields: JARVIS (bandgap, mbj_bandgap, formation_energy, bulk/shear modulus, epsx/y/z, etc.) + Polymer Genome (poly_id, label, method, src, vol, atom_en, hse_gap, gga_gap, diel_tot, diel_ion, diel_elec) + structure info.
+
+
+---
+
+## Python Examples
+
+=== "Fetch data"
+
+    ```python
+    import requests
+
+    response = requests.get(
+        "https://atomgpt.org/polymer/data/JVASP-1002",
+        headers={"Authorization": "Bearer sk-XYZ"},
+    )
+    data = response.json()
+    print(f"{data['formula']} — {data['label']}")
+    print(f"  JARVIS gap: {data['bandgap']} eV, PG HSE gap: {data['hse_gap_pg']} eV")
+    print(f"  Dielectric: total={data['diel_tot']}, elec={data['diel_elec']}")
+    ```
+
+
 ## AGAPI Agent
 
 ```python
 from agapi.agents import AGAPIAgent
 import os
-
 agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
-response = agent.query_sync("Show polymer explorer for Silicon")
+response = agent.query_sync("Show polymer explorer data")
 print(response)
 ```
 
-## Reference
+## References
 
-- Sci. Data 3, 160012 (2016)
+- K. Choudhary et al., Sci. Data 3, 160012 (2016) [:material-link: DOI](https://doi.org/10.1038/sdata.2016.12)
+- [atomgptlab/jarvis](https://github.com/atomgptlab/jarvis)
diff --git a/docs/apps/explore/pourbaix.md b/docs/apps/explore/pourbaix.md
new file mode 100644
index 0000000..1a43658
--- /dev/null
+++ b/docs/apps/explore/pourbaix.md
@@ -0,0 +1,66 @@
+---
+title: PourbaixMat
+---
+
+# PourbaixMat
+
+Compute Pourbaix (electrochemical aqueous stability) diagrams from JARVIS-DFT formation energies + ASE Pourbaix thermodynamic engine. Supports configurable pH/potential ranges, ionic concentration, temperature, and manual energy overrides. Returns heatmap, stability region, and phase map data for the target material.
+
+[:material-open-in-new: Open App](https://atomgpt.org/pourbaix){ .md-button .md-button--primary }
+
+---
+
+## Overview
+
+!!! info "Data Source"
+    **JARVIS dft_3d** (formation energies, auto-fetched) + **ASE** (solvated ion refs from Johnson 1992 / Pourbaix atlas).
+
+## Endpoints
+
+### `POST /pourbaix/predict` — Compute Pourbaix diagram
+
+```bash
+curl -X POST "https://atomgpt.org/pourbaix/predict" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -d '{"element": "Zn", "target": "ZnO", "solids": ["Zn", "ZnO"]}'
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `element` | string | required | Metal element symbol |
+| `target` | string | required | Target formula |
+| `solids` | list[string] | [] | Competing solid phases |
+| `manual_energies` | dict | {} | Override formation energies (eV/f.u.) |
+| `U_min/U_max` | float | -2/2 | Potential range (V vs SHE) |
+| `pH_min/pH_max` | float | 0/14 | pH range |
+| `resolution` | int | 60 | Grid resolution (20–120) |
+| `conc` | float | 1e-6 | Ionic concentration (mol/L) |
+| `temperature` | float | 298.15 | Temperature (K) |
+| `use_jarvis` | bool | true | Auto-fetch from JARVIS-DFT |
+
+**Response:** `pH` array, `U` array, `energies[pH][U]` (ΔG in eV), `phases[pH][U]` (competing phase names), `refs_used`, `stable_frac`.
+
+---
+
+### `GET /pourbaix/jarvis_search` — Search JARVIS cache
+
+```bash
+curl "https://atomgpt.org/pourbaix/jarvis_search?q=ZnO" -H "Authorization: Bearer sk-XYZ"
+```
+
+
+## AGAPI Agent
+
+```python
+from agapi.agents import AGAPIAgent
+import os
+agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
+response = agent.query_sync("Show pourbaixmat data")
+print(response)
+```
+
+## References
+
+- K. Choudhary et al., npj Comp. Mat. 6, 173 (2020) [:material-link: DOI](https://doi.org/10.1038/s41524-020-00440-1)
+- [atomgptlab/jarvis](https://github.com/atomgptlab/jarvis)
diff --git a/docs/apps/explore/reaction-network.md b/docs/apps/explore/reaction-network.md
index 94037d4..f5919cb 100644
--- a/docs/apps/explore/reaction-network.md
+++ b/docs/apps/explore/reaction-network.md
@@ -4,7 +4,7 @@ title: Reaction Network
 
 # Reaction Network
 
-Balance chemical equations (SVD null-space), compute reaction thermodynamics ΔH from JARVIS-DFT formation energies, and build interactive d3.js bipartite reaction network graphs.
+Three-endpoint chemistry toolkit: (1) Balance — balances chemical equations using SVD null-space method. (2) Thermodynamics — computes reaction enthalpy ΔH from JARVIS-DFT formation energies with per-species energy breakdown. (3) Network — builds bipartite reaction network graphs (species ↔ reaction nodes) from a list of equations.
 
 [:material-open-in-new: Open App](https://atomgpt.org/reaction_network){ .md-button .md-button--primary }
 
@@ -12,52 +12,84 @@ Balance chemical equations (SVD null-space), compute reaction thermodynamics ΔH
 
 ## Overview
 
-Balance chemical equations (SVD null-space), compute reaction thermodynamics ΔH from JARVIS-DFT formation energies, and build interactive d3.js bipartite reaction network graphs.
-
 !!! info "Data Source"
-    **dft_3d (formation energies)**
+    **JARVIS dft_3d** — formation energies (OptB88vdW) mapped by formula, with diatomic aliases (O₂→O, N₂→N, etc.).
 
 ## Endpoints
 
-- `GET /reaction_network`
-- `POST /reaction_network/balance`
-- `POST /reaction_network/thermodynamics`
-- `POST /reaction_network/network`
+### `POST /reaction_network/balance` — Balance equation
+
+```bash
+curl -X POST "https://atomgpt.org/reaction_network/balance" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -d '{"reactants": "Fe2O3 + C", "products": "Fe + CO2"}'
+```
 
-**Request Models:** `BalanceRequest`, `ThermodynamicsRequest`, `NetworkRequest`
+Returns `react_coeffs`, `prod_coeffs`, `balanced` (bool), element counts for verification.
 
-!!! note "Authentication"
-    All POST endpoints require `Authorization: Bearer YOUR_TOKEN`.
+---
 
-## API Example
+### `POST /reaction_network/thermodynamics` — Reaction ΔH
 
-```python
-import requests
-
-response = requests.post(
-    "https://atomgpt.org/reaction_network/balance",
-    headers={
-        "Authorization": "Bearer sk-XYZ",
-        "accept": "application/json",
-        "Content-Type": "application/json",
-    },
-    json={"equation": "Fe2O3 + C -> Fe + CO2"},
-)
-data = response.json()
-print(data)
+```bash
+curl -X POST "https://atomgpt.org/reaction_network/thermodynamics" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -d '{"reactants": ["SrO", "TiO2"], "products": ["SrTiO3"], "react_coeffs": [1, 1], "prod_coeffs": [1]}'
+```
+
+Returns per-species formation energy (from JARVIS-DFT), total energies, `delta_h`, `feasible` (exothermic if ΔH < 0). Includes diatomic aliases (O₂→O, N₂→N).
+
+---
+
+### `POST /reaction_network/network` — Build reaction graph
+
+```bash
+curl -X POST "https://atomgpt.org/reaction_network/network" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -d '{"reactions": ["H2 + O2 -> H2O", "CH4 + 2O2 -> CO2 + 2H2O"]}'
 ```
 
+Returns `nodes` (species + reaction), `edges` (with coefficients), for d3.js bipartite graph rendering.
+
+
+---
+
+## Python Examples
+
+=== "Balance + ΔH"
+
+    ```python
+    import requests
+    H = {"Authorization": "Bearer sk-XYZ", "Content-Type": "application/json"}
+
+    # Balance
+    r = requests.post("https://atomgpt.org/reaction_network/balance", headers=H,
+        json={"reactants": "Fe2O3 + C", "products": "Fe + CO2"})
+    b = r.json()
+    print(f"Balanced: {b['react_coeffs']} -> {b['prod_coeffs']}")
+
+    # Thermodynamics
+    r = requests.post("https://atomgpt.org/reaction_network/thermodynamics", headers=H,
+        json={"reactants": ["SrO", "TiO2"], "products": ["SrTiO3"]})
+    t = r.json()
+    print(f"ΔH = {t['delta_h']} eV, Feasible: {t['feasible']}")
+    ```
+
+
 ## AGAPI Agent
 
 ```python
 from agapi.agents import AGAPIAgent
 import os
-
 agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
-response = agent.query_sync("Show reaction network for Silicon")
+response = agent.query_sync("Show reaction network data")
 print(response)
 ```
 
-## Reference
+## References
 
-- NPJ Comp. Mat. 6, 173 (2020)
+- K. Choudhary et al., npj Comp. Mat. 6, 173 (2020) [:material-link: DOI](https://doi.org/10.1038/s41524-020-00440-1)
+- [atomgptlab/jarvis](https://github.com/atomgptlab/jarvis)
diff --git a/docs/apps/explore/sdss.md b/docs/apps/explore/sdss.md
new file mode 100644
index 0000000..a15b52a
--- /dev/null
+++ b/docs/apps/explore/sdss.md
@@ -0,0 +1,74 @@
+---
+title: SDSS SkyServer Explorer
+---
+
+# SDSS SkyServer Explorer
+
+Query the Sloan Digital Sky Survey (DR18) — 4M+ spectra of stars, galaxies, and quasars. Supports custom SQL queries (CasJobs syntax), radial/cone search by sky coordinates, and sky image cutouts. Preset queries for bright galaxies, quasars (z>2), cool stars, AGN hosts, and white dwarfs.
+
+[:material-open-in-new: Open App](https://atomgpt.org/sdss){ .md-button .md-button--primary }
+
+---
+
+## Overview
+
+!!! info "Data Source"
+    **SDSS SkyServer DR18** REST API (skyserver.sdss.org).
+
+## Endpoints
+
+### `POST /sdss/query` — Run SQL query
+
+```bash
+curl -X POST "https://atomgpt.org/sdss/query" \
+  -H "Content-Type: application/json" \
+  -d '{"preset": "galaxies_bright"}'
+```
+
+Or custom SQL:
+
+```bash
+curl -X POST "https://atomgpt.org/sdss/query" \
+  -H "Content-Type: application/json" \
+  -d '{"sql": "SELECT TOP 10 p.objID, p.ra, p.dec, s.z AS redshift FROM PhotoObj p JOIN SpecObj s ON s.bestobjid=p.objid WHERE s.class=\'GALAXY\'"}'
+```
+
+### `GET /sdss/query` — API key auth
+
+```bash
+curl "https://atomgpt.org/sdss/query?preset=quasars&APIKEY=sk-XYZ"
+```
+
+---
+
+### `POST /sdss/radial_search` — Cone search
+
+```bash
+curl -X POST "https://atomgpt.org/sdss/radial_search" \
+  -H "Content-Type: application/json" \
+  -d '{"ra": 197.614, "dec": 18.438, "radius": 1.0, "limit": 50}'
+```
+
+### `GET /sdss/image_url` — Sky image cutout URL
+
+```bash
+curl "https://atomgpt.org/sdss/image_url?ra=197.614&dec=18.438&scale=0.4&width=256&height=256"
+```
+
+**Presets:** `galaxies_bright, quasars, stars_cool, supernovae_host, white_dwarfs`.
+
+
+## AGAPI Agent
+
+```python
+from agapi.agents import AGAPIAgent
+import os
+agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
+response = agent.query_sync("Show sdss skyserver explorer data")
+print(response)
+```
+
+## References
+
+- Sloan Digital Sky Survey [:material-link: DOI](https://www.sdss.org)
+- [atomgptlab/jarvis](https://github.com/atomgptlab/jarvis)
diff --git a/docs/apps/explore/spillage.md b/docs/apps/explore/spillage.md
index 33bec8d..cba21b5 100644
--- a/docs/apps/explore/spillage.md
+++ b/docs/apps/explore/spillage.md
@@ -1,10 +1,10 @@
 ---
-title: Spillage
+title: Spillage Explorer
 ---
 
-# Spillage
+# Spillage Explorer
 
-Visualize and compare SOC spillage data from JARVIS-DFT for identifying topological insulators and semimetals. Data parsed from JARVIS XML.
+Visualize and compare spin-orbit coupling (SOC) spillage data from JARVIS-DFT for identifying topological insulators and semimetals. Returns per-k-point spillage values, k-point coordinates, max spillage, and topological classification (spillage > 0.5 = non-trivial). Data parsed from JARVIS XML.
 
 [:material-open-in-new: Open App](https://atomgpt.org/spillage){ .md-button .md-button--primary }
 
@@ -12,40 +12,94 @@ Visualize and compare SOC spillage data from JARVIS-DFT for identifying topologi
 
 ## Overview
 
-Visualize and compare SOC spillage data from JARVIS-DFT for identifying topological insulators and semimetals. Data parsed from JARVIS XML.
-
 !!! info "Data Source"
-    **dft_3d (JARVIS XML)**
+    **JARVIS-DFT** — SOC spillage from JARVIS XML (`<spillage_k>`, `<max_spillage>`, `<spillage_kpoints>` tags).
 
 ## Endpoints
 
-- `GET /spillage`
-- `POST /spillage/search`
-- `GET /spillage/data/{jid}`
+### `POST /spillage/search` — Search materials
 
-**Request Models:** `SpillageSearchRequest`
+```bash
+curl -X POST "https://atomgpt.org/spillage/search" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{"formula": "Si"}'
+```
 
-!!! note "Authentication"
-    All POST endpoints require `Authorization: Bearer YOUR_TOKEN`.
+Standard search fields: `formula`, `jid`, `elements`, `element_mode` (any/all/exact), `bandgap_min`, `bandgap_max`, `spacegroup`. Max 500 results.
 
-## API Example
+!!! note
+    Pre-filtered to materials with `spillage != 'na'`.
 
-```python
-import requests
-
-response = requests.post(
-    "https://atomgpt.org/spillage/search",
-    headers={
-        "Authorization": "Bearer sk-XYZ",
-        "accept": "application/json",
-        "Content-Type": "application/json",
-    },
-    json={"jid": "JVASP-1002"},
-)
-data = response.json()
-print(data)
+---
+
+### `GET /spillage/data/{jid}` — Fetch per-k-point spillage values and topological classification.
+
+```bash
+curl "https://atomgpt.org/spillage/data/JVASP-1002" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "accept: application/json"
 ```
 
+**Response:**
+
+```json
+{
+  "jid": "JVASP-1002",
+  "formula": "Si",
+  "bandgap": 0.611,
+  "max_spillage": 0.32,
+  "spillage_k": [0.12, 0.15, 0.32, 0.08, ...],
+  "kpoints": [[0.0, 0.0, 0.0], [0.1, 0.0, 0.0], ...],
+  "k_indices": [0, 1, 2, 3, ...],
+  "n_kpoints": 50,
+  "n_above_threshold": 0,
+  "topological_classification": "Topologically trivial (spillage <= 0.5)"
+}
+```
+
+Spillage > 0.5 indicates topologically non-trivial band inversion. `n_above_threshold` counts k-points with spillage > 0.5. K-points parsed from semicolon-separated `kx;ky;kz` format.
+
+---
+
+## Python Examples
+
+=== "Search"
+
+    ```python
+    import requests
+
+    response = requests.post(
+        "https://atomgpt.org/spillage/search",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={"formula": "Si"},
+    )
+    data = response.json()
+    print(f"Found {data['total']} entries")
+    for m in data["results"][:5]:
+        print(f"  {m['jid']}: {m.get('formula', m.get('bulk_formula', ''))}")
+    ```
+
+=== "Fetch data"
+
+    ```python
+    import requests
+
+    response = requests.get(
+        "https://atomgpt.org/spillage/data/JVASP-1002",
+        headers={"Authorization": "Bearer sk-XYZ"},
+    )
+    data = response.json()
+    print(f"{data['formula']}: {data['topological_classification']}")
+    print(f"  Max spillage: {data['max_spillage']}")
+    print(f"  K-points above 0.5: {data['n_above_threshold']}/{data['n_kpoints']}")
+    ```
+
 ## AGAPI Agent
 
 ```python
@@ -53,10 +107,11 @@ from agapi.agents import AGAPIAgent
 import os
 
 agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
-response = agent.query_sync("Show spillage for Silicon")
+response = agent.query_sync("Show spillage explorer for Silicon")
 print(response)
 ```
 
-## Reference
+## References
 
-- Sci. Rep. 9, 8534 (2019)
+- K. Choudhary et al., Sci. Rep. 9, 8534 (2019) [:material-link: DOI](https://doi.org/10.1038/s41598-019-45028-y)
+- [atomgptlab/jarvis](https://github.com/atomgptlab/jarvis)
diff --git a/docs/apps/explore/surface.md b/docs/apps/explore/surface.md
index 20b14ac..41870be 100644
--- a/docs/apps/explore/surface.md
+++ b/docs/apps/explore/surface.md
@@ -4,7 +4,7 @@ title: Surface Explorer
 
 # Surface Explorer
 
-Browse, search, and visualize surface properties from the JARVIS surface database (607 entries). Work functions, surface energies, and cleavage energies.
+Browse, search, and visualize surface properties from the JARVIS surface database (607 entries). Surface energies, work functions, Fermi levels, VBM/CBM, and electrostatic potential profiles. Filter by formula, JID, Miller indices, and surface energy range.
 
 [:material-open-in-new: Open App](https://atomgpt.org/surface){ .md-button .md-button--primary }
 
@@ -12,40 +12,104 @@ Browse, search, and visualize surface properties from the JARVIS surface databas
 
 ## Overview
 
-Browse, search, and visualize surface properties from the JARVIS surface database (607 entries). Work functions, surface energies, and cleavage energies.
-
 !!! info "Data Source"
-    **surfacedb (607 entries)**
+    **JARVIS surfacedb** — 607 surface slab entries from `jarvis.db.figshare.data('surfacedb')`.
 
 ## Endpoints
 
-- `GET /surface`
-- `POST /surface/search`
-- `GET /surface/data/{idx}`
+### `POST /surface/search` — Search materials
 
-**Request Models:** `SurfaceSearchRequest`
+```bash
+curl -X POST "https://atomgpt.org/surface/search" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{"formula": "Si"}'
+```
 
-!!! note "Authentication"
-    All POST endpoints require `Authorization: Bearer YOUR_TOKEN`.
+| Field | Type | Description |
+|-------|------|-------------|
+| `formula` | string | Formula substring |
+| `jid` | string | JARVIS ID (extracted from surface name) |
+| `miller` | string | Miller index string (e.g. '110') |
+| `surf_en_min` | float | Min surface energy |
+| `surf_en_max` | float | Max surface energy |
 
-## API Example
+**Response fields:** `idx, name, jid, miller, thickness, formula, surf_en, efermi, scf_vbm, scf_cbm, surf_vbm, surf_cbm`.
 
-```python
-import requests
-
-response = requests.post(
-    "https://atomgpt.org/surface/search",
-    headers={
-        "Authorization": "Bearer sk-XYZ",
-        "accept": "application/json",
-        "Content-Type": "application/json",
-    },
-    json={"jid": "JVASP-1002"},
-)
-data = response.json()
-print(data)
+---
+
+### `GET /surface/data/{idx (integer)}` — Fetch full surface record by index.
+
+```bash
+curl "https://atomgpt.org/surface/data/JVASP-1002" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "accept: application/json"
 ```
 
+**Response:**
+
+```json
+{
+  "idx": 42,
+  "name": "Surface-JVASP-1002_miller_1_1_1_thickness_16_VASP_PBE_noDP",
+  "jid": "JVASP-1002",
+  "miller": "(1 1 1)",
+  "thickness": "16",
+  "method": "VASP PBE",
+  "formula": "Si",
+  "surf_en": 1.36,
+  "efermi": 4.52,
+  "scf_vbm": -5.73, "scf_cbm": -4.52,
+  "surf_vbm": -5.73, "surf_cbm": -4.52,
+  "avg_max": 8.2,
+  "phi": [0.1, 0.2, ...],
+  "slab": {"n_atoms": 32, "elements": ["Si"], "abc": [3.84, 3.84, 40.0], "angles": [90, 90, 90]}
+}
+```
+
+Surface name parsed for JID, Miller indices, and thickness. `phi` is the electrostatic potential profile (1D array along z-axis). Surface energy in J/m².
+
+---
+
+## Python Examples
+
+=== "Search"
+
+    ```python
+    import requests
+
+    response = requests.post(
+        "https://atomgpt.org/surface/search",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={"formula": "Si"},
+    )
+    data = response.json()
+    print(f"Found {data['total']} entries")
+    for m in data["results"][:5]:
+        print(f"  {m['jid']}: {m.get('formula', m.get('bulk_formula', ''))}")
+    ```
+
+=== "Fetch data"
+
+    ```python
+    import requests
+
+    response = requests.get(
+        "https://atomgpt.org/surface/data/JVASP-1002",
+        headers={"Authorization": "Bearer sk-XYZ"},
+    )
+    data = response.json()
+    print(f"{data['formula']} {data['miller']} surface")
+    print(f"  Surface energy: {data['surf_en']} J/m²")
+    print(f"  Work function proxy: {data['avg_max']}")
+    print(f"  Slab: {data['slab']['n_atoms']} atoms")
+    ```
+
 ## AGAPI Agent
 
 ```python
@@ -57,6 +121,7 @@ response = agent.query_sync("Show surface explorer for Silicon")
 print(response)
 ```
 
-## Reference
+## References
 
-- Digital Discovery (2024)
+- K. Choudhary et al., Digital Discovery (2024) [:material-link: DOI](https://doi.org/10.1039/D4DD00031E)
+- [atomgptlab/jarvis](https://github.com/atomgptlab/jarvis)
diff --git a/docs/apps/explore/thermoelectric.md b/docs/apps/explore/thermoelectric.md
index 74ac17e..a8eabad 100644
--- a/docs/apps/explore/thermoelectric.md
+++ b/docs/apps/explore/thermoelectric.md
@@ -4,7 +4,7 @@ title: Thermoelectric
 
 # Thermoelectric
 
-Visualize and compare thermoelectric (BoltzTrap) data from JARVIS-DFT. Seebeck coefficient, electrical conductivity, and power factor parsed from JARVIS XML pages.
+Visualize and compare thermoelectric (BoltzTrap) data from JARVIS-DFT. The data is fetched by parsing JARVIS XML pages for the `<main_boltz><boltztrap_info>` section. Returns Seebeck coefficient, electrical conductivity, power factor, and electronic thermal conductivity for both n-type and p-type carriers (xx, yy, zz components).
 
 [:material-open-in-new: Open App](https://atomgpt.org/thermoelectric){ .md-button .md-button--primary }
 
@@ -12,40 +12,129 @@ Visualize and compare thermoelectric (BoltzTrap) data from JARVIS-DFT. Seebeck c
 
 ## Overview
 
-Visualize and compare thermoelectric (BoltzTrap) data from JARVIS-DFT. Seebeck coefficient, electrical conductivity, and power factor parsed from JARVIS XML pages.
+Search materials by formula, JARVIS ID, elements, space group, or property ranges. Click any result to fetch and plot the full spectrum. All search results are capped at 500 entries.
 
 !!! info "Data Source"
-    **dft_3d (JARVIS XML)**
+    **JARVIS-DFT** — BoltzTrap data parsed from JARVIS XML pages (`<main_boltz><boltztrap_info>` section).
 
 ## Endpoints
 
-- `GET /thermoelectric`
-- `POST /thermoelectric/search`
-- `GET /thermoelectric/data/{jid}`
+### `POST /thermoelectric/search` — Search materials
 
-**Request Models:** `ThermoelectricSearchRequest`
+```bash
+curl -X POST "https://atomgpt.org/thermoelectric/search" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "formula": "Si"
+  }'
+```
+
+Search with elements:
+
+```bash
+curl -X POST "https://atomgpt.org/thermoelectric/search" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "elements": ["Ti", "O"],
+    "element_mode": "all"
+  }'
+```
 
-!!! note "Authentication"
-    All POST endpoints require `Authorization: Bearer YOUR_TOKEN`.
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `formula` | string | null | Chemical formula |
+| `jid` | string | null | Exact JARVIS ID |
+| `elements` | list[string] | null | Element symbols |
+| `element_mode` | string | "any" | "any", "all", or "exact" |
+| `bandgap_min` | float | null | Min OptB88vdW band gap (eV) |
+| `bandgap_max` | float | null | Max OptB88vdW band gap (eV) |
+| `spacegroup` | string | null | Space group substring |
 
-## API Example
+**Response fields:** `jid, formula, spacegroup, optb88vdw_bandgap, mbj_bandgap, magmom`.
 
-```python
-import requests
-
-response = requests.post(
-    "https://atomgpt.org/thermoelectric/search",
-    headers={
-        "Authorization": "Bearer sk-XYZ",
-        "accept": "application/json",
-        "Content-Type": "application/json",
-    },
-    json={"jid": "JVASP-1002"},
-)
-data = response.json()
-print(data)
+!!! note
+    Pre-filtered to materials with `n-Seebeck != 'na'` (materials that have BoltzTrap data).
+
+---
+
+### `GET /thermoelectric/data/{jid}` — Fetch spectrum data
+
+Fetch BoltzTrap thermoelectric properties by parsing the JARVIS XML page for the material.
+
+```bash
+curl "https://atomgpt.org/thermoelectric/data/JVASP-1002" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "accept: application/json"
+```
+
+**Response:**
+
+```json
+{
+  "jid": "JVASP-1002",
+  "formula": "Si",
+  "bandgap": 0.611,
+  "properties": {
+    "pseeb": [230.23, 230.23, 230.23],
+    "pcond": [1.2e14, 1.2e14, 1.2e14],
+    "ppf": [6.35, 6.35, 6.35],
+    "pkappa": [0.89, 0.89, 0.89],
+    "nseeb": [-195.5, -195.5, -195.5],
+    "ncond": [2.1e14, 2.1e14, 2.1e14],
+    "npf": [8.02, 8.02, 8.02],
+    "nkappa": [1.12, 1.12, 1.12]
+  }
+}
 ```
 
+8 properties, each a 3-component vector [xx, yy, zz]: `pseeb` (p-Seebeck, μV/K), `pcond` (p-conductivity, 1/(Ω·m)), `ppf` (p-power factor, μW/(mK²)), `pkappa` (p-κ_e, W/(mK)), and the n-type equivalents. XML fetched from `https://www.ctcms.nist.gov/~knc6/static/JARVIS-DFT/{JID}.xml`.
+
+---
+
+## Python Examples
+
+=== "Search"
+
+    ```python
+    import requests
+
+    response = requests.post(
+        "https://atomgpt.org/thermoelectric/search",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={"formula": "Si"},
+    )
+    data = response.json()
+    print(f"Found {data['total']} materials")
+    for m in data["results"][:5]:
+        print(f"  {m['jid']}: {m['formula']}")
+    ```
+
+=== "Fetch data"
+
+    ```python
+    import requests
+
+    response = requests.get(
+        "https://atomgpt.org/thermoelectric/data/JVASP-1002",
+        headers={"Authorization": "Bearer sk-XYZ"},
+    )
+    data = response.json()
+    props = data["properties"]
+    print(f"{data['formula']}")
+    if "pseeb" in props:
+        print(f"  p-Seebeck: {props['pseeb']} μV/K")
+    if "nseeb" in props:
+        print(f"  n-Seebeck: {props['nseeb']} μV/K")
+    ```
+
 ## AGAPI Agent
 
 ```python
@@ -57,6 +146,7 @@ response = agent.query_sync("Show thermoelectric for Silicon")
 print(response)
 ```
 
-## Reference
+## References
 
-- J. Phys. Cond. Matt. 32, 475501 (2020)
+- K. Choudhary et al., J. Phys.: Condens. Matter 32, 475501 (2020) [:material-link: DOI](https://doi.org/10.1088/1361-648X/aba06b)
+- [atomgptlab/jarvis](https://github.com/atomgptlab/jarvis)
diff --git a/docs/apps/explore/tokenizer.md b/docs/apps/explore/tokenizer.md
new file mode 100644
index 0000000..0c1e843
--- /dev/null
+++ b/docs/apps/explore/tokenizer.md
@@ -0,0 +1,110 @@
+---
+title: Tokenizer Playground
+---
+
+# Tokenizer Playground
+
+Visualize how different tokenizers break text into tokens. Supports tiktoken encodings (GPT-4, GPT-3.5, GPT-2, o200k), plus character-level and whitespace tokenizers for comparison. Shows token count, character count, per-token text, and token IDs.
+
+[:material-open-in-new: Open App](https://atomgpt.org/tokenizer){ .md-button .md-button--primary }
+
+---
+
+## Overview
+
+!!! info "Data Source"
+    **tiktoken** library — cl100k_base, o200k_base, gpt2, p50k_base, p50k_edit, r50k_base encodings.
+
+## Endpoints
+
+### `POST /tokenizer/tokenize` — Tokenize text
+
+```bash
+curl -X POST "https://atomgpt.org/tokenizer/tokenize" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -d '{"text": "SrTiO3 is a perovskite oxide", "tokenizer": "cl100k_base"}'
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `text` | string | required | Input text (max 50,000 characters) |
+| `tokenizer` | string | `cl100k_base` | Tokenizer name (see below) |
+
+**Available tokenizers:**
+
+| Name | Description |
+|------|-------------|
+| `gpt-4 / gpt-4o / gpt-3.5-turbo` | cl100k_base (GPT-4/3.5 family) |
+| `gpt-4o (o200k)` | o200k_base (GPT-4o optimized) |
+| `gpt-2` | GPT-2 BPE tokenizer |
+| `cl100k_base` | Direct encoding name |
+| `o200k_base` | Direct encoding name |
+| `p50k_base` | Codex-era encoding |
+| `character` | Character-level (1 char = 1 token) |
+| `whitespace` | Whitespace + punctuation split |
+
+**Response:**
+
+```json
+{
+  "tokenizer": "cl100k_base",
+  "text": "SrTiO3 is a perovskite oxide",
+  "n_tokens": 9,
+  "n_chars": 28,
+  "tokens": ["Sr", "Ti", "O", "3", " is", " a", " per", "ovsk", "ite oxide"],
+  "token_ids": [21521, 46465, 46, 18, 374, 264, 824, 17487, 1029]
+}
+```
+
+---
+
+## Python Examples
+
+=== "Tokenize"
+
+    ```python
+    import requests
+
+    response = requests.post(
+        "https://atomgpt.org/tokenizer/tokenize",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "Content-Type": "application/json",
+        },
+        json={"text": "SrTiO3 is a perovskite oxide", "tokenizer": "cl100k_base"},
+    )
+    data = response.json()
+    print(f"Tokens: {data['n_tokens']}, Chars: {data['n_chars']}")
+    for tok, tid in zip(data["tokens"], data["token_ids"]):
+        print(f"  [{tid}] {repr(tok)}")
+    ```
+
+=== "Compare tokenizers"
+
+    ```python
+    import requests
+
+    text = "La2CuO4 superconductor Tc=40K"
+    H = {"Authorization": "Bearer sk-XYZ", "Content-Type": "application/json"}
+    for tok in ["cl100k_base", "o200k_base", "gpt-2", "character"]:
+        r = requests.post("https://atomgpt.org/tokenizer/tokenize",
+            headers=H, json={"text": text, "tokenizer": tok})
+        d = r.json()
+        print(f"  {tok}: {d['n_tokens']} tokens")
+    ```
+
+## AGAPI Agent
+
+```python
+from agapi.agents import AGAPIAgent
+import os
+agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
+response = agent.query_sync("Tokenize SrTiO3 with GPT-4 tokenizer")
+print(response)
+```
+
+## References
+
+- [OpenAI tiktoken](https://github.com/openai/tiktoken)
+- [atomgptlab/jarvis](https://github.com/atomgptlab/jarvis)
diff --git a/docs/apps/explore/twod.md b/docs/apps/explore/twod.md
index 0d6f7a2..8c2d58a 100644
--- a/docs/apps/explore/twod.md
+++ b/docs/apps/explore/twod.md
@@ -1,10 +1,10 @@
 ---
-title: 2D Materials
+title: 2D Materials Explorer
 ---
 
-# 2D Materials
+# 2D Materials Explorer
 
-Browse, search, and visualize properties of 2D materials from the JARVIS-DFT 2D dataset (~1.1K monolayers). Exfoliation energies, band gaps, magnetic properties.
+Browse, search, and visualize properties of ~1,100 2D monolayer materials from the JARVIS-DFT 2D dataset. Filter by formula, elements, space group, band gap, exfoliation energy, and magnetic state. Full property card with 30+ fields per material.
 
 [:material-open-in-new: Open App](https://atomgpt.org/twod){ .md-button .md-button--primary }
 
@@ -12,51 +12,75 @@ Browse, search, and visualize properties of 2D materials from the JARVIS-DFT 2D
 
 ## Overview
 
-Browse, search, and visualize properties of 2D materials from the JARVIS-DFT 2D dataset (~1.1K monolayers). Exfoliation energies, band gaps, magnetic properties.
-
 !!! info "Data Source"
-    **dft_2d (~1.1K entries)**
+    **JARVIS dft_2d** — ~1,100 2D monolayer entries from `jarvis.db.figshare.data('dft_2d')`.
 
 ## Endpoints
 
-- `GET /twod`
-- `POST /twod/search`
-- `GET /twod/data/{jid}`
+### `POST /twod/search` — Search materials
 
-**Request Models:** `TwoDSearchRequest`
+```bash
+curl -X POST "https://atomgpt.org/twod/search" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -d '{"formula": "MoS2"}'
+```
 
-!!! note "Authentication"
-    All POST endpoints require `Authorization: Bearer YOUR_TOKEN`.
+| Field | Type | Description |
+|-------|------|-------------|
+| `formula` | string | Chemical formula |
+| `jid` | string | JARVIS ID |
+| `elements` | list[string] | Element symbols |
+| `element_mode` | string | "any" or "all" |
+| `spacegroup` | string | Space group symbol or number |
+| `bandgap_min/max` | float | OptB88vdW band gap range (eV) |
+| `exfol_min/max` | float | Exfoliation energy range (meV/atom) |
+| `magnetic` | string | "yes", "no", or null (any) |
 
-## API Example
+**Response:** `jid, formula, spg_symbol, bandgap, mbj_bandgap, exfoliation_energy, magmom, spillage, ehull, formation_energy`.
 
-```python
-import requests
-
-response = requests.post(
-    "https://atomgpt.org/twod/search",
-    headers={
-        "Authorization": "Bearer sk-XYZ",
-        "accept": "application/json",
-        "Content-Type": "application/json",
-    },
-    json={"jid": "JVASP-1002"},
-)
-data = response.json()
-print(data)
+---
+
+### `GET /twod/data/{jid}` — Full record
+
+```bash
+curl "https://atomgpt.org/twod/data/JVASP-664" \
+  -H "Authorization: Bearer sk-XYZ"
 ```
 
+**Response:** 30+ fields: bandgap, mbj_bandgap, hse_gap, formation_energy, exfoliation_energy, magmom, spillage, slme, ehull, Tc_supercon, epsx/y/z, mepsx/y/z, max_efg, dfpt_piezo_max_eij, max_ir_mode, n/p-Seebeck, bulk/shear modulus, poisson, structure info.
+
+
+---
+
+## Python Examples
+
+=== "Fetch data"
+
+    ```python
+    import requests
+
+    response = requests.get(
+        "https://atomgpt.org/twod/data/JVASP-1002",
+        headers={"Authorization": "Bearer sk-XYZ"},
+    )
+    data = response.json()
+    print(f"{data['formula']} ({data['spg_symbol']})")
+    print(f"  Band gap: {data['bandgap']} eV, Exfoliation: {data['exfoliation_energy']} meV/atom")
+    ```
+
+
 ## AGAPI Agent
 
 ```python
 from agapi.agents import AGAPIAgent
 import os
-
 agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
-response = agent.query_sync("Show 2d materials for Silicon")
+response = agent.query_sync("Show 2d materials explorer data")
 print(response)
 ```
 
-## Reference
+## References
 
-- Sci. Rep. 7, 5179 (2017)
+- K. Choudhary et al., Sci. Rep. 7, 5179 (2017) [:material-link: DOI](https://doi.org/10.1038/s41598-017-05402-0)
+- [atomgptlab/jarvis](https://github.com/atomgptlab/jarvis)
diff --git a/docs/apps/explore/unit-converter.md b/docs/apps/explore/unit-converter.md
new file mode 100644
index 0000000..363e984
--- /dev/null
+++ b/docs/apps/explore/unit-converter.md
@@ -0,0 +1,52 @@
+---
+title: Unit Converter
+---
+
+# Unit Converter
+
+Convert between units for the seven SI fundamental quantities: Length, Mass, Time, Electric Current, Temperature, Amount of Substance, and Luminous Intensity. All conversion logic is client-side JavaScript; the backend only serves the HTML template.
+
+[:material-open-in-new: Open App](https://atomgpt.org/unit_converter){ .md-button .md-button--primary }
+
+---
+
+## Overview
+
+!!! info "Data Source"
+    Client-side only — no backend data.
+
+## Endpoint
+
+### `GET /unit_converter` — HTML page
+
+```bash
+curl "https://atomgpt.org/unit_converter"
+```
+
+This is a client-side-only app with no API endpoints. The backend serves only the HTML page containing JavaScript unit conversion logic.
+
+!!! note
+    No authentication required. No POST/JSON endpoints — all computation happens in-browser.
+
+---
+
+## Supported Quantity Categories
+
+Length, Mass, Time, Electric Current, Temperature, Amount of Substance, Luminous Intensity.
+
+---
+
+## AGAPI Agent
+
+```python
+from agapi.agents import AGAPIAgent
+import os
+agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
+response = agent.query_sync("Convert 1 angstrom to nanometers")
+print(response)
+```
+
+## References
+
+- [NIST SI Units](https://www.nist.gov/pml/owm/metric-si/si-units)
+- [atomgptlab/jarvis](https://github.com/atomgptlab/jarvis)
diff --git a/docs/apps/explore/vacancy.md b/docs/apps/explore/vacancy.md
index 7e450bf..51312a8 100644
--- a/docs/apps/explore/vacancy.md
+++ b/docs/apps/explore/vacancy.md
@@ -4,7 +4,7 @@ title: Vacancy Explorer
 
 # Vacancy Explorer
 
-Browse, search, and visualize vacancy formation energies from the JARVIS vacancy database (464 entries). Dataset loaded from jarvis.db.figshare.data('vacancydb').
+Browse, search, and visualize vacancy formation energies from the JARVIS vacancy database (464 entries). Filter by bulk formula, vacancy element, Wyckoff position, material type, and formation energy range. Each entry includes bulk and defective structures, chemical potentials, and energetics.
 
 [:material-open-in-new: Open App](https://atomgpt.org/vacancy){ .md-button .md-button--primary }
 
@@ -12,40 +12,103 @@ Browse, search, and visualize vacancy formation energies from the JARVIS vacancy
 
 ## Overview
 
-Browse, search, and visualize vacancy formation energies from the JARVIS vacancy database (464 entries). Dataset loaded from jarvis.db.figshare.data('vacancydb').
-
 !!! info "Data Source"
-    **vacancydb (464 entries)**
+    **JARVIS vacancydb** — 464 vacancy defect entries from `jarvis.db.figshare.data('vacancydb')`.
 
 ## Endpoints
 
-- `GET /vacancy`
-- `POST /vacancy/search`
-- `GET /vacancy/data/{defect_id}`
+### `POST /vacancy/search` — Search materials
 
-**Request Models:** `VacancySearchRequest`
+```bash
+curl -X POST "https://atomgpt.org/vacancy/search" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{"formula": "Si"}'
+```
 
-!!! note "Authentication"
-    All POST endpoints require `Authorization: Bearer YOUR_TOKEN`.
+| Field | Type | Description |
+|-------|------|-------------|
+| `formula` | string | Bulk formula substring |
+| `jid` | string | JARVIS ID substring |
+| `symbol` | string | Vacancy element symbol |
+| `wycoff` | string | Wyckoff position |
+| `material_type` | string | Material type (metal, semiconductor, etc.) |
+| `ef_min` | float | Min formation energy (eV) |
+| `ef_max` | float | Max formation energy (eV) |
 
-## API Example
+**Response fields:** `id, jid, bulk_formula, symbol, wycoff, ef, material_type, chem_pot, bulk_energy, defective_energy`.
 
-```python
-import requests
-
-response = requests.post(
-    "https://atomgpt.org/vacancy/search",
-    headers={
-        "Authorization": "Bearer sk-XYZ",
-        "accept": "application/json",
-        "Content-Type": "application/json",
-    },
-    json={"jid": "JVASP-1002"},
-)
-data = response.json()
-print(data)
+---
+
+### `GET /vacancy/data/{defect_id}` — Fetch full vacancy defect record by defect ID.
+
+```bash
+curl "https://atomgpt.org/vacancy/data/JVASP-1002" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "accept: application/json"
 ```
 
+**Response:**
+
+```json
+{
+  "id": "JVASP-867_Cu_a",
+  "jid": "JVASP-867",
+  "bulk_formula": "Cu",
+  "symbol": "Cu",
+  "wycoff": "a",
+  "ef": 1.234,
+  "chem_pot": -3.456,
+  "bulk_energy": -14.567,
+  "defective_energy": -10.234,
+  "material_type": "metal",
+  "bulk": {"n_atoms": 4, "elements": ["Cu"], "abc": [3.61, 3.61, 3.61], "angles": [90.0, 90.0, 90.0]},
+  "defective": {"n_atoms": 3, "elements": ["Cu"], "abc": [3.61, 3.61, 3.61], "angles": [90.0, 90.0, 90.0]}
+}
+```
+
+Formation energy: E_f = E_defective - E_bulk + μ_element. Defect ID format: `{JID}_{element}_{wyckoff}` (e.g. `JVASP-867_Cu_a`).
+
+---
+
+## Python Examples
+
+=== "Search"
+
+    ```python
+    import requests
+
+    response = requests.post(
+        "https://atomgpt.org/vacancy/search",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={"formula": "Si"},
+    )
+    data = response.json()
+    print(f"Found {data['total']} entries")
+    for m in data["results"][:5]:
+        print(f"  {m['jid']}: {m.get('formula', m.get('bulk_formula', ''))}")
+    ```
+
+=== "Fetch data"
+
+    ```python
+    import requests
+
+    response = requests.get(
+        "https://atomgpt.org/vacancy/data/JVASP-1002",
+        headers={"Authorization": "Bearer sk-XYZ"},
+    )
+    data = response.json()
+    print(f"{data['bulk_formula']} vacancy at {data['symbol']} ({data['wycoff']})")
+    print(f"  Formation energy: {data['ef']:.3f} eV")
+    print(f"  Bulk atoms: {data['bulk']['n_atoms']}, Defective: {data['defective']['n_atoms']}")
+    ```
+
 ## AGAPI Agent
 
 ```python
@@ -57,6 +120,7 @@ response = agent.query_sync("Show vacancy explorer for Silicon")
 print(response)
 ```
 
-## Reference
+## References
 
-- AIP Advances 13(9) (2023)
+- K. Choudhary, AIP Advances 13(9) (2023) [:material-link: DOI](https://doi.org/10.1063/5.0159299)
+- [atomgptlab/jarvis](https://github.com/atomgptlab/jarvis)
diff --git a/docs/apps/explore/webbrowser.md b/docs/apps/explore/webbrowser.md
new file mode 100644
index 0000000..1cff9e3
--- /dev/null
+++ b/docs/apps/explore/webbrowser.md
@@ -0,0 +1,65 @@
+---
+title: Web Browser
+---
+
+# Web Browser
+
+Search the web via DuckDuckGo and fetch/extract content from any URL. Returns clean text, links, images, and metadata. Supports configurable extraction options.
+
+[:material-open-in-new: Open App](https://atomgpt.org/webbrowser){ .md-button .md-button--primary }
+
+---
+
+## Overview
+
+!!! info "Data Source"
+    **DuckDuckGo Search** (no API key) + **BeautifulSoup** (HTML parsing).
+
+## Endpoints
+
+### `POST /webbrowser/search` — Search the web
+
+```bash
+curl -X POST "https://atomgpt.org/webbrowser/search" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -d '{"query": "perovskite solar cells 2024", "max_results": 10}'
+```
+
+**Response:** `query, total, results[]` (title, url, snippet).
+
+---
+
+### `POST /webbrowser/fetch` — Fetch and extract URL content
+
+```bash
+curl -X POST "https://atomgpt.org/webbrowser/fetch" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -d '{"url": "https://en.wikipedia.org/wiki/Perovskite", "extract_text": true, "extract_links": true}'
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `url` | string | required | URL to fetch |
+| `extract_text` | bool | true | Extract clean text (max 10K chars) |
+| `extract_links` | bool | false | Extract links (max 200) |
+| `extract_images` | bool | false | Extract images (max 100) |
+
+**Response:** `url, status_code, content_type, title, meta_description, text, word_count, links[], images[], fetch_time_s`.
+
+
+## AGAPI Agent
+
+```python
+from agapi.agents import AGAPIAgent
+import os
+agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
+response = agent.query_sync("Show web browser data")
+print(response)
+```
+
+## References
+
+- DuckDuckGo Search [:material-link: DOI](https://github.com/deedy5/duckduckgo_search)
+- [atomgptlab/jarvis](https://github.com/atomgptlab/jarvis)
diff --git a/docs/apps/index.md b/docs/apps/index.md
index 36e6863..8475a63 100644
--- a/docs/apps/index.md
+++ b/docs/apps/index.md
@@ -2,20 +2,19 @@
 title: Apps Overview
 description: All 50+ AtomGPT web applications organized by category
 ---
-
 # Apps Overview
 
-AtomGPT.org hosts **50+ web applications** for materials science. Each app provides a web interface, REST API endpoints, and Python examples for agentic workflows.
+AtomGPT.org hosts **54 web applications** for materials science, AI, and scientific exploration. Each app provides a web interface, REST API endpoints, and Python examples for agentic workflows.
 
 ## Categories
 
 | Category | Apps | Description |
 |----------|------|-------------|
-| [**Explore**](explore/) | 22 | Browse databases, search materials, visualize properties |
-| [**Build**](build/) | 4 | Construct structures, design workflows, write code |
+| [**Explore**](explore/) | 32 | Browse databases, search materials, visualize properties, literature, astronomy |
+| [**Build**](build/) | 5 | Construct structures, build polymers, design workflows, web terminal |
 | [**Predict**](predict/) | 6 | ML predictions, force fields, quantum algorithms |
 | [**Characterize**](characterize/) | 3 | Match spectra, analyze images, identify structures |
-| [**Apply**](apply/) | 5 | Screen materials for specific applications |
+| [**Apply**](apply/) | 8 | Screen materials, predict hardness, melting points, corrosion stability |
 | [**Validate**](validate/) | 2 | Verify AI outputs, check references |
 
 ## Architecture
@@ -35,4 +34,4 @@ Every app follows the same pattern:
 
 - **Frontend**: Single HTML file with embedded CSS/JS, dark theme
 - **Backend**: FastAPI route with authentication, served from `custom_routes/`
-- **Data**: JARVIS-DFT (76K materials), ALIGNN models, Wannier TBH databases
+- **Data**: JARVIS-DFT (76K materials), ALIGNN models, Wannier TBH databases, external APIs (RCSB PDB, OMIM, SDSS, arXiv, Crossref)
diff --git a/docs/apps/predict/alignn-ff.md b/docs/apps/predict/alignn-ff.md
index 51804a1..4f77f45 100644
--- a/docs/apps/predict/alignn-ff.md
+++ b/docs/apps/predict/alignn-ff.md
@@ -4,7 +4,7 @@ title: ALIGNN-FF Dynamics
 
 # ALIGNN-FF Dynamics
 
-Universal ML force field. Structure relaxation (BFGS), geometry optimization, NVT/NPT molecular dynamics, and phonon calculations — all via ALIGNN-FF. Supports model selection (default or wt01).
+Universal ML force field for atomistic simulations. Three tabs: (1) Geometry Optimization — relax structures with FIRE/BFGS/LBFGS, (2) Molecular Dynamics — NVE simulations with Maxwell-Boltzmann initialization, (3) Phonon Bandstructure — finite-displacement phonon calculations via phonopy. All powered by ALIGNN-FF (`AlignnAtomwiseCalculator`).
 
 [:material-open-in-new: Open App](https://atomgpt.org/alignn_ff_dynamics){ .md-button .md-button--primary }
 
@@ -12,44 +12,240 @@ Universal ML force field. Structure relaxation (BFGS), geometry optimization, NV
 
 ## Overview
 
-Universal ML force field. Structure relaxation (BFGS), geometry optimization, NVT/NPT molecular dynamics, and phonon calculations — all via ALIGNN-FF. Supports model selection (default or wt01).
+The ALIGNN-FF app provides a complete atomistic simulation toolkit in the browser. The force field is a pretrained ALIGNN model that predicts energy, forces, and stress for any crystal structure. The app supports geometry optimization with trajectory playback, molecular dynamics with energy/temperature monitoring, and phonon bandstructure calculation via phonopy with interactive Plotly plots.
 
 !!! info "Data Source"
-    **ALIGNN-FF pretrained model**
+    **ALIGNN-FF** — `AlignnAtomwiseCalculator` from `alignn.ff.ff` (default or wt01 model).
+    **phonopy** — for phonon dispersion via finite displacement method.
 
 ## Endpoints
 
-- `GET /alignn_ff_dynamics`
-- `GET /alignn_ff/query`
-- `POST /alignn_ff/query`
-- `GET /alignn_ff/relax`
-- `POST /alignn_ff/optimize`
-- `POST /alignn_ff/md`
-- `POST /alignn_ff/phonons`
+### `GET /alignn_ff/query` — Single-point energy (API key)
 
-**Request Models:** `OptimizationRequest`, `MDRequest`, `PhononRequest`
+Compute energy, forces, and stress for a structure without relaxation.
 
-!!! note "Authentication"
-    All POST endpoints require `Authorization: Bearer YOUR_TOKEN`.
+```bash
+curl "https://atomgpt.org/alignn_ff/query?poscar=Si%0A1.0%0A0%202.734%202.734%0A2.734%200%202.734%0A2.734%202.734%200%0ASi%0A2%0Adirect%0A0%200%200%0A0.25%200.25%200.25&APIKEY=sk-XYZ" \
+  -H "accept: application/json"
+```
 
-## API Example
+Returns `energy_eV`, `forces_eV_per_A` (Nx3 array), `stress` (6-component Voigt), `natoms`.
 
-```python
-import requests
-
-response = requests.post(
-    "https://atomgpt.org/alignn_ff/query",
-    headers={
-        "Authorization": "Bearer sk-XYZ",
-        "accept": "application/json",
-        "Content-Type": "application/json",
-    },
-    json={"jid": "JVASP-1002"},
-)
-data = response.json()
-print(data)
+---
+
+### `GET /alignn_ff/relax` — Quick relaxation (plain text POSCAR)
+
+Relax a structure and return the optimized POSCAR as plain text.
+
+```bash
+curl "https://atomgpt.org/alignn_ff/relax?poscar=Si%0A1.0%0A5.0%200%200%0A0%205.0%200%0A0%200%205.0%0ASi%0A8%0Adirect%0A0.25%200.75%200.25%0A0%200%200.5%0A0.25%200.25%200.75%0A0%200.5%200%0A0.75%200.75%200.75%0A0.5%200%200%0A0.75%200.25%200.25%0A0.5%200.5%200.5&fmax=0.05&steps=50&APIKEY=sk-XYZ"
+```
+
+| Param | Default | Description |
+|-------|---------|-------------|
+| `poscar` | required | URL-encoded POSCAR |
+| `fmax` | 0.05 | Force convergence tolerance (eV/Å) |
+| `steps` | 50 | Max relaxation steps |
+
+Returns plain text relaxed POSCAR.
+
+---
+
+### `POST /alignn_ff/optimize` — Full optimization with trajectory
+
+Geometry optimization with full trajectory data for visualization and playback.
+
+```bash
+curl -X POST "https://atomgpt.org/alignn_ff/optimize" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "poscar": "Si\n1.0\n5.0 0 0\n0 5.0 0\n0 0 5.0\nSi\n8\ndirect\n0.25 0.75 0.25\n0 0 0.5\n0.25 0.25 0.75\n0 0.5 0\n0.75 0.75 0.75\n0.5 0 0\n0.75 0.25 0.25\n0.5 0.5 0.5",
+    "fmax": 0.05,
+    "steps": 100,
+    "optimizer": "FIRE",
+    "relax_cell": true
+  }'
 ```
 
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `poscar` | string | required | VASP POSCAR structure (max 100 atoms) |
+| `fmax` | float | 0.05 | Force convergence (eV/Å) |
+| `steps` | int | 200 | Max optimization steps |
+| `optimizer` | string | `"FIRE"` | `"FIRE"`, `"BFGS"`, or `"LBFGS"` |
+| `relax_cell` | bool | true | Also optimize cell parameters (via ExpCellFilter) |
+
+**Response** includes `converged`, `final_poscar`, `initial_energy`, `final_energy`, `energy_change`, `steps_taken`, `energies` (per-step), `forces_max` (per-step), `trajectory` (positions/cell every 5 steps for playback), `computation_time`.
+
+---
+
+### `POST /alignn_ff/md` — Molecular dynamics
+
+NVE molecular dynamics with Maxwell-Boltzmann velocity initialization and VelocityVerlet integrator.
+
+```bash
+curl -X POST "https://atomgpt.org/alignn_ff/md" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "poscar": "Si\n1.0\n5.494 0 0\n0 5.494 0\n0 0 5.494\nSi\n8\ndirect\n0.25 0.75 0.25\n0 0 0.5\n0.25 0.25 0.75\n0 0.5 0\n0.75 0.75 0.75\n0.5 0 0\n0.75 0.25 0.25\n0.5 0.5 0.5",
+    "temperature": 300.0,
+    "timestep": 0.5,
+    "steps": 50,
+    "interval": 5
+  }'
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `poscar` | string | required | POSCAR structure (max 50 atoms) |
+| `temperature` | float | 300.0 | Initial temperature (K) |
+| `timestep` | float | 0.5 | Integration timestep (fs) |
+| `steps` | int | 50 | Number of MD steps |
+| `interval` | int | 5 | Save trajectory every N steps |
+
+**Response** includes `trajectory` (positions, velocities, T, KE, PE per saved frame), `energies` (total/kinetic/potential arrays), `temperatures`, `average_temperature`, `final_temperature`, `computation_time`.
+
+---
+
+### `POST /alignn_ff/phonons` — Phonon bandstructure
+
+Relax the structure, then compute phonon dispersion via phonopy finite displacements.
+
+```bash
+curl -X POST "https://atomgpt.org/alignn_ff/phonons" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "poscar": "Si\n1.0\n5.494 0 0\n0 5.494 0\n0 0 5.494\nSi\n8\ndirect\n0.25 0.75 0.25\n0 0 0.5\n0.25 0.25 0.75\n0 0.5 0\n0.75 0.75 0.75\n0.5 0 0\n0.75 0.25 0.25\n0.5 0.5 0.5",
+    "fmax": 0.05,
+    "relax_steps": 50,
+    "force_multiplier": 1.9,
+    "dim": [2, 2, 2],
+    "relax_cell": true
+  }'
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `poscar` | string | required | POSCAR structure (max 50 atoms) |
+| `fmax` | float | 0.05 | Force convergence for pre-relaxation (eV/Å) |
+| `relax_steps` | int | 50 | Max relaxation steps |
+| `force_multiplier` | float | 1.9 | Force scaling for phonopy |
+| `dim` | list[int] | `[2,2,2]` | Supercell dimensions for phonon calculation |
+| `relax_cell` | bool | true | Relax cell before phonon calc |
+
+**Response** includes `relaxed_poscar`, `primitive_poscar`, `band_data` (distances + frequencies for interactive Plotly), `plot_base64` (PNG fallback), `supercell_dim`, `computation_time`.
+
+---
+
+## Python Examples
+
+=== "Optimize structure"
+
+    ```python
+    import requests
+
+    response = requests.post(
+        "https://atomgpt.org/alignn_ff/optimize",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={
+            "poscar": open("POSCAR").read(),
+            "fmax": 0.05,
+            "steps": 100,
+            "optimizer": "FIRE",
+            "relax_cell": True,
+        },
+    )
+    data = response.json()
+    print(f"Converged: {data['converged']}")
+    print(f"E: {data['initial_energy']:.4f} → {data['final_energy']:.4f} eV")
+    print(f"Steps: {data['steps_taken']}, Time: {data['computation_time']}s")
+    with open("CONTCAR", "w") as f:
+        f.write(data["final_poscar"])
+    ```
+
+=== "Molecular dynamics"
+
+    ```python
+    import requests
+
+    response = requests.post(
+        "https://atomgpt.org/alignn_ff/md",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={
+            "poscar": open("POSCAR").read(),
+            "temperature": 300.0,
+            "timestep": 0.5,
+            "steps": 100,
+            "interval": 10,
+        },
+    )
+    data = response.json()
+    print(f"Avg T: {data['average_temperature']:.1f} K")
+    print(f"Frames: {len(data['trajectory'])}")
+    ```
+
+=== "Phonon bandstructure"
+
+    ```python
+    import requests
+
+    response = requests.post(
+        "https://atomgpt.org/alignn_ff/phonons",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={
+            "poscar": open("POSCAR").read(),
+            "dim": [2, 2, 2],
+            "force_multiplier": 1.9,
+        },
+    )
+    data = response.json()
+    print(f"Primitive atoms: {data['num_atoms_prim']}")
+    print(f"Supercell: {data['supercell_dim']}")
+    print(f"Time: {data['computation_time']}s")
+
+    # Save phonon plot
+    if data.get("plot_base64"):
+        import base64
+        with open("phonon_bands.png", "wb") as f:
+            f.write(base64.b64decode(data["plot_base64"]))
+    ```
+
+=== "Single-point energy"
+
+    ```python
+    import requests
+
+    response = requests.get(
+        "https://atomgpt.org/alignn_ff/query",
+        headers={"accept": "application/json"},
+        params={
+            "poscar": open("POSCAR").read(),
+            "APIKEY": "sk-XYZ",
+        },
+    )
+    data = response.json()
+    print(f"Energy: {data['energy_eV']:.4f} eV")
+    print(f"Max force: {max(max(abs(f) for f in row) for row in data['forces_eV_per_A']):.4f} eV/Å")
+    ```
+
 ## AGAPI Agent
 
 ```python
@@ -57,10 +253,22 @@ from agapi.agents import AGAPIAgent
 import os
 
 agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
-response = agent.query_sync("Show alignn-ff dynamics for Silicon")
+
+# Relax structure
+response = agent.query_sync("Relax the structure of JVASP-1002 using ALIGNN-FF")
+print(response)
+
+# Run MD
+response = agent.query_sync("Run molecular dynamics on Si at 500K for 100 steps")
+print(response)
+
+# Phonons
+response = agent.query_sync("Compute the phonon bandstructure of Si using ALIGNN-FF")
 print(response)
 ```
 
-## Reference
+## References
 
-- Digital Discovery 2(2), 346 (2023)
+- K. Choudhary, Digital Discovery 2(2), 346 (2023) — ALIGNN-FF [:material-link: DOI](https://doi.org/10.1039/D2DD00096B)
+- K. Choudhary, B. DeCost, npj Comp. Mat. 7, 185 (2021) — ALIGNN [:material-link: DOI](https://doi.org/10.1038/s41524-021-00650-1)
+- [atomgptlab/alignn](https://github.com/atomgptlab/alignn)
diff --git a/docs/apps/predict/alignn.md b/docs/apps/predict/alignn.md
index bfc41dd..622bd3c 100644
--- a/docs/apps/predict/alignn.md
+++ b/docs/apps/predict/alignn.md
@@ -4,7 +4,7 @@ title: ALIGNN Predictor
 
 # ALIGNN Predictor
 
-Predict 50+ materials properties with ALIGNN graph neural networks. Query by JARVIS ID or upload POSCAR. Web prediction endpoint returns all available model predictions.
+Predict 15+ materials properties simultaneously using ALIGNN (Atomistic Line Graph Neural Network) pretrained models. Input by JARVIS ID or POSCAR structure. Properties span energy/stability, electronic band gaps, mechanical moduli, dielectric/piezoelectric constants, topological spillage, SLME, magnetic moment, superconducting Tc, and interface band offsets.
 
 [:material-open-in-new: Open App](https://atomgpt.org/alignn){ .md-button .md-button--primary }
 
@@ -12,41 +12,186 @@ Predict 50+ materials properties with ALIGNN graph neural networks. Query by JAR
 
 ## Overview
 
-Predict 50+ materials properties with ALIGNN graph neural networks. Query by JARVIS ID or upload POSCAR. Web prediction endpoint returns all available model predictions.
+The ALIGNN Predictor runs 15 pretrained ALIGNN models in one call to predict a comprehensive set of materials properties from crystal structure alone. Max 50 atoms per structure. Three endpoints are available: GET (API key auth), POST (session auth for web UI), and web_predict (structured JSON response with all 15 properties organized by category).
 
 !!! info "Data Source"
-    **ALIGNN pretrained models**
+    **ALIGNN pretrained models** — 15+ models from [`alignn.pretrained`](https://github.com/atomgptlab/alignn/blob/main/alignn/pretrained.py), trained on JARVIS-DFT data.
+
+## Predicted Properties
+
+| Category | Property | Unit | Model Key |
+|----------|----------|------|-----------|
+| Energy | Formation energy | eV/atom | `jv_formation_energy_peratom_alignn` |
+| Energy | Total energy (OptB88vdW) | eV/atom | `jv_optb88vdw_total_energy_alignn` |
+| Energy | Energy above hull | eV/atom | `jv_ehull_alignn` |
+| Electronic | Band gap (OptB88vdW) | eV | `jv_optb88vdw_bandgap_alignn` |
+| Electronic | Band gap (mBJ) | eV | `jv_mbj_bandgap_alignn` |
+| Mechanical | Bulk modulus (Kv) | GPa | `jv_bulk_modulus_kv_alignn` |
+| Mechanical | Shear modulus (Gv) | GPa | `jv_shear_modulus_gv_alignn` |
+| Dielectric | Dielectric constant (εx) | — | `jv_epsx_alignn` |
+| Piezoelectric | Piezoelectric constant | — | `jv_dfpt_piezo_max_dielectric_alignn` |
+| Topological | SOC spillage | — | `jv_spillage_alignn` |
+| Optical | SLME | % | `jv_slme_alignn` |
+| Magnetic | Magnetic moment | μB | `jv_magmom_oszicar_alignn` |
+| Superconducting | Tc | K | `jv_supercon_tc_alignn` |
+| Interface | CBM (InterMat) | eV | `intermat_cbm` |
+| Interface | VBM (InterMat) | eV | `intermat_vbm` |
 
 ## Endpoints
 
-- `GET /alignn`
-- `GET /alignn/query`
-- `POST /alignn/query`
-- `POST /alignn/web_predict`
+### `GET /alignn/query` — Predict by JARVIS ID or POSCAR (API key)
 
-**Request Models:** —
+```bash
+curl "https://atomgpt.org/alignn/query?jid=JVASP-1002&APIKEY=sk-XYZ" \
+  -H "accept: application/json"
+```
+
+With POSCAR string (URL-encoded):
 
-!!! note "Authentication"
-    All POST endpoints require `Authorization: Bearer YOUR_TOKEN`.
+```bash
+curl "https://atomgpt.org/alignn/query?poscar=Si%0A1.0%0A0%202.734%202.734%0A2.734%200%202.734%0A2.734%202.734%200%0ASi%0A2%0Adirect%0A0%200%200%0A0.25%200.25%200.25&APIKEY=sk-XYZ" \
+  -H "accept: application/json"
+```
 
-## API Example
+| Param | Description |
+|-------|-------------|
+| `jid` | JARVIS ID (e.g. `JVASP-1002`) — provide `jid` OR `poscar` |
+| `poscar` | URL-encoded POSCAR string |
+| `APIKEY` | API key (query parameter auth) |
 
-```python
-import requests
-
-response = requests.post(
-    "https://atomgpt.org/alignn/query",
-    headers={
-        "Authorization": "Bearer sk-XYZ",
-        "accept": "application/json",
-        "Content-Type": "application/json",
-    },
-    json={"jid": "JVASP-1002"},
-)
-data = response.json()
-print(data)
+Returns raw prediction dict with all model keys.
+
+---
+
+### `POST /alignn/query` — Predict from file or string (session auth)
+
+Upload a POSCAR file:
+
+```bash
+curl -X POST "https://atomgpt.org/alignn/query" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -F "file=@POSCAR"
+```
+
+Or submit as form string:
+
+```bash
+curl -X POST "https://atomgpt.org/alignn/query" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -F "poscar_string=Si
+1.0
+0 2.734 2.734
+2.734 0 2.734
+2.734 2.734 0
+Si
+2
+direct
+0 0 0
+0.25 0.25 0.25"
 ```
 
+---
+
+### `POST /alignn/web_predict` — Structured predictions (JSON body)
+
+Returns all 15 properties organized in a clean structure with formula and atom count.
+
+```bash
+curl -X POST "https://atomgpt.org/alignn/web_predict" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "poscar": "Si\n1.0\n0 2.734 2.734\n2.734 0 2.734\n2.734 2.734 0\nSi\n2\ndirect\n0 0 0\n0.25 0.25 0.25"
+  }'
+```
+
+**Response:**
+
+```json
+{
+  "formula": "Si",
+  "num_atoms": 2,
+  "properties": {
+    "formation_energy": -0.005,
+    "total_energy": -5.412,
+    "ehull": 0.0,
+    "bandgap_optb88": 0.611,
+    "bandgap_mbj": 1.156,
+    "bulk_modulus": 88.9,
+    "shear_modulus": 51.5,
+    "epsx": 12.3,
+    "piezoelectric": 0.0,
+    "spillage": 0.32,
+    "slme": 5.2,
+    "magmom": 0.0,
+    "supercon_tc": 0.0,
+    "intermat_cbm": -4.1,
+    "intermat_vbm": -5.3
+  }
+}
+```
+
+---
+
+## Python Examples
+
+=== "Query by JID"
+
+    ```python
+    import requests
+
+    response = requests.get(
+        "https://atomgpt.org/alignn/query",
+        headers={"accept": "application/json"},
+        params={"jid": "JVASP-1002", "APIKEY": "sk-XYZ"},
+    )
+    data = response.json()
+    print(f"Band gap (OptB88): {data['jv_optb88vdw_bandgap_alignn'][0]:.3f} eV")
+    print(f"Formation energy: {data['jv_formation_energy_peratom_alignn'][0]:.3f} eV/atom")
+    ```
+
+=== "Web predict (structured)"
+
+    ```python
+    import requests
+
+    response = requests.post(
+        "https://atomgpt.org/alignn/web_predict",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={"poscar": open("POSCAR").read()},
+    )
+    data = response.json()
+    print(f"{data['formula']} ({data['num_atoms']} atoms)")
+    p = data["properties"]
+    print(f"  Formation energy: {p['formation_energy']:.3f} eV/atom")
+    print(f"  Band gap (OPT): {p['bandgap_optb88']:.3f} eV")
+    print(f"  Band gap (MBJ): {p['bandgap_mbj']:.3f} eV")
+    print(f"  Bulk modulus: {p['bulk_modulus']:.1f} GPa")
+    print(f"  Supercon Tc: {p['supercon_tc']:.2f} K")
+    ```
+
+=== "Upload POSCAR file"
+
+    ```python
+    import requests
+
+    with open("POSCAR", "rb") as f:
+        response = requests.post(
+            "https://atomgpt.org/alignn/query",
+            headers={"Authorization": "Bearer sk-XYZ"},
+            files={"file": ("POSCAR", f)},
+        )
+    data = response.json()
+    for key, val in sorted(data.items()):
+        if key.endswith("_alignn") or key.startswith("intermat"):
+            print(f"  {key}: {val}")
+    ```
+
 ## AGAPI Agent
 
 ```python
@@ -54,10 +199,18 @@ from agapi.agents import AGAPIAgent
 import os
 
 agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
-response = agent.query_sync("Show alignn predictor for Silicon")
+
+# Predict properties
+response = agent.query_sync("Predict all ALIGNN properties for JVASP-1002")
+print(response)
+
+# Compare materials
+response = agent.query_sync("Compare the band gap of Si and GaAs using ALIGNN")
 print(response)
 ```
 
-## Reference
+## References
 
-- NPJ Comp. Mat. 7, 1 (2021)
+- K. Choudhary, B. DeCost, npj Comp. Mat. 7, 185 (2021) — ALIGNN [:material-link: DOI](https://doi.org/10.1038/s41524-021-00650-1)
+- K. Choudhary, Comp. Mat. Sci. 259, 114063 (2025) [:material-link: DOI](https://doi.org/10.1016/j.commatsci.2025.114063)
+- [atomgptlab/alignn](https://github.com/atomgptlab/alignn)
diff --git a/docs/apps/predict/protein-fold.md b/docs/apps/predict/protein-fold.md
index 0e834af..f3f953a 100644
--- a/docs/apps/predict/protein-fold.md
+++ b/docs/apps/predict/protein-fold.md
@@ -4,7 +4,7 @@ title: Protein Fold
 
 # Protein Fold
 
-Protein structure prediction using ESMFold/OpenFold. Paste amino acid sequence, get 3D structure with pLDDT confidence. Web endpoint for interactive folding.
+Protein structure prediction using ESMFold (Meta) and OpenFold3 (NVIDIA). Paste an amino acid sequence to get a 3D PDB structure with interactive 3Dmol viewer. Two backends: ESMFold via the ESM Atlas API for single-chain folding, and OpenFold3 via NVIDIA Health API for protein-DNA complex prediction.
 
 [:material-open-in-new: Open App](https://atomgpt.org/protein_fold){ .md-button .md-button--primary }
 
@@ -12,42 +12,160 @@ Protein structure prediction using ESMFold/OpenFold. Paste amino acid sequence,
 
 ## Overview
 
-Protein structure prediction using ESMFold/OpenFold. Paste amino acid sequence, get 3D structure with pLDDT confidence. Web endpoint for interactive folding.
+The Protein Fold app provides two structure prediction backends. ESMFold takes a single amino acid sequence (10–400 residues) and returns a PDB structure via Meta's ESM Atlas API. OpenFold3 takes a protein sequence plus two DNA sequences and predicts the protein-DNA complex via NVIDIA's Health API. The web UI includes an interactive 3Dmol viewer with cartoon/sphere/stick/line rendering, spin control, and PDB download.
 
 !!! info "Data Source"
-    **ESMFold / OpenFold models**
+    **ESMFold** — `api.esmatlas.com/foldSequence/v1/pdb/` (Meta AI).
+    **OpenFold3** — `health.api.nvidia.com` (NVIDIA BioNeMo).
 
 ## Endpoints
 
-- `GET /protein_fold`
-- `GET /protein_fold/query`
-- `POST /protein_fold/query`
-- `POST /protein_fold/predict`
-- `GET /openfold/query`
+### `POST /protein_fold/predict` — Fold sequence (web UI, JSON)
 
-**Request Models:** `ProteinFoldRequest`
+Predict 3D structure from amino acid sequence. Returns PDB content, atom count, residue count, amino acid composition, and molecular weight.
 
-!!! note "Authentication"
-    All POST endpoints require `Authorization: Bearer YOUR_TOKEN`.
+```bash
+curl -X POST "https://atomgpt.org/protein_fold/predict" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "sequence": "MKTAYIAKQRQISFVKSHFSRQLEERLGLIEVQAPILSRVGDGTQDNLSGAEKAVQVKVKALPDAQFEVVHSLAKWKRQQQ"
+  }'
+```
 
-## API Example
+| Field | Type | Description |
+|-------|------|-------------|
+| `sequence` | string | Amino acid sequence (standard one-letter codes: ACDEFGHIKLMNPQRSTVWY, 10–400 residues) |
 
-```python
-import requests
-
-response = requests.post(
-    "https://atomgpt.org/protein_fold/query",
-    headers={
-        "Authorization": "Bearer sk-XYZ",
-        "accept": "application/json",
-        "Content-Type": "application/json",
-    },
-    json={"jid": "JVASP-1002"},
-)
-data = response.json()
-print(data)
+**Response:**
+
+| Field | Description |
+|-------|-------------|
+| `pdb_content` | Full PDB file content |
+| `sequence` | Cleaned uppercase sequence |
+| `sequence_length` | Number of residues |
+| `num_atoms` | Total atoms in PDB |
+| `num_residues` | Unique residue count |
+| `composition` | Amino acid composition dict (e.g. `{"ALA": 5, "GLY": 3}`) |
+| `molecular_weight` | Estimated molecular weight (Da) |
+
+---
+
+### `GET /protein_fold/query` — Fold sequence (API key, plain text PDB)
+
+Returns the raw PDB file as plain text.
+
+```bash
+curl "https://atomgpt.org/protein_fold/query?sequence=MKTAYIAKQRQISFVKSHFS&APIKEY=sk-XYZ" \
+  -H "accept: text/plain" \
+  --output structure.pdb
+```
+
+---
+
+### `POST /protein_fold/query` — Fold sequence (session auth, ZIP or JSON)
+
+Returns PDB as a ZIP file (default) or JSON.
+
+```bash
+curl -X POST "https://atomgpt.org/protein_fold/query" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -d "sequence=MKTAYIAKQRQISFVKSHFS&format=zip" \
+  --output protein_structure.zip
 ```
 
+| Param | Default | Description |
+|-------|---------|-------------|
+| `sequence` | required | Amino acid sequence |
+| `format` | `"zip"` | `"zip"` (PDB in ZIP archive) or `"json"` (PDB as JSON string) |
+
+---
+
+### `GET /openfold/query` — Protein-DNA complex (NVIDIA OpenFold3)
+
+Predict a protein-DNA complex structure using NVIDIA's OpenFold3 API.
+
+```bash
+curl "https://atomgpt.org/openfold/query?protein_sequence=MKTAYIAKQRQISFVKSHFS&dna1=ATCGATCG&dna2=CGATCGAT&APIKEY=sk-XYZ" \
+  -H "accept: text/plain" \
+  --output complex.pdb
+```
+
+| Param | Description |
+|-------|-------------|
+| `protein_sequence` | Protein amino acid sequence |
+| `dna1` | First DNA strand sequence |
+| `dna2` | Second DNA strand sequence (complementary) |
+
+Returns plain-text PDB of the predicted complex.
+
+---
+
+## Python Examples
+
+=== "Fold a protein"
+
+    ```python
+    import requests
+
+    response = requests.post(
+        "https://atomgpt.org/protein_fold/predict",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={
+            "sequence": "KVFGRCELAAAMKRHGLDNYRGYSLGNWVCAAKFESNFNTQATNRNTDGSTDYGILQINSRWWCNDGRTPGSRNLCNIPCSALLSSDITASVNCAKKIVSDGNGMNAWVAWRNRCKGTDVQAWIRGCRL"
+        },
+    )
+    data = response.json()
+    if data["success"]:
+        print(f"Residues: {data['num_residues']}")
+        print(f"Atoms: {data['num_atoms']}")
+        print(f"MW: {data['molecular_weight']:.0f} Da")
+        with open("structure.pdb", "w") as f:
+            f.write(data["pdb_content"])
+        print("Saved structure.pdb")
+    ```
+
+=== "Get raw PDB"
+
+    ```python
+    import requests
+
+    response = requests.get(
+        "https://atomgpt.org/protein_fold/query",
+        params={
+            "sequence": "MKTAYIAKQRQISFVKSHFS",
+            "APIKEY": "sk-XYZ",
+        },
+    )
+    with open("peptide.pdb", "w") as f:
+        f.write(response.text)
+    ```
+
+=== "Protein-DNA complex"
+
+    ```python
+    import requests
+
+    response = requests.get(
+        "https://atomgpt.org/openfold/query",
+        params={
+            "protein_sequence": "MKTAYIAKQRQISFVKSHFSRQLEERLGLIEVQAPILSRVGD",
+            "dna1": "ATCGATCGATCG",
+            "dna2": "CGATCGATCGAT",
+            "APIKEY": "sk-XYZ",
+        },
+    )
+    with open("complex.pdb", "w") as f:
+        f.write(response.text)
+    print("Saved protein-DNA complex PDB")
+    ```
+
 ## AGAPI Agent
 
 ```python
@@ -55,10 +173,14 @@ from agapi.agents import AGAPIAgent
 import os
 
 agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
-response = agent.query_sync("Show protein fold for Silicon")
+
+# Fold protein
+response = agent.query_sync("Fold this protein sequence: MKTAYIAKQRQISFVKSHFS")
 print(response)
 ```
 
-## Reference
+## References
 
-- Science (2023)
+- Z. Lin et al., Science 379, 1123 (2023) — ESMFold [:material-link: DOI](https://doi.org/10.1126/science.ade2574)
+- [facebookresearch/esm](https://github.com/facebookresearch/esm)
+- [NVIDIA OpenFold3](https://health.api.nvidia.com)
diff --git a/docs/apps/predict/quantum.md b/docs/apps/predict/quantum.md
index 15d2f9c..1be4e63 100644
--- a/docs/apps/predict/quantum.md
+++ b/docs/apps/predict/quantum.md
@@ -4,7 +4,7 @@ title: Quantum Computation
 
 # Quantum Computation
 
-Run Qiskit VQE/VQD on Wannier tight-binding Hamiltonians from JARVIS-DFT using statevector simulator. EfficientSU2 (circuit6) ansatz. Full bandstructure via JARVIS get_bandstruct.
+Run quantum chemistry simulations on Wannier tight-binding Hamiltonians from JARVIS-DFT. Two tabs: (1) VQE — variational quantum eigensolver at a single k-point using Qiskit statevector simulator with EfficientSU2 (circuit6) ansatz, returning ground-state energy, Pauli decomposition, and circuit diagram; (2) Bandstructure — full VQD bandstructure across the Brillouin zone via JARVIS `get_bandstruct`, comparing quantum (VQD) vs classical (NumPy) eigenvalues. Supports both electron and phonon Hamiltonians.
 
 [:material-open-in-new: Open App](https://atomgpt.org/quantum){ .md-button .md-button--primary }
 
@@ -12,41 +12,229 @@ Run Qiskit VQE/VQD on Wannier tight-binding Hamiltonians from JARVIS-DFT using s
 
 ## Overview
 
-Run Qiskit VQE/VQD on Wannier tight-binding Hamiltonians from JARVIS-DFT using statevector simulator. EfficientSU2 (circuit6) ansatz. Full bandstructure via JARVIS get_bandstruct.
+The Quantum Computation app bridges Wannier tight-binding Hamiltonians with quantum computing. It loads the WTBH from JARVIS-DFT, builds H(k) at the requested k-point, decomposes it into a sum of Pauli operators, then runs Qiskit VQE (or VQD for bandstructure) on a statevector simulator. The EfficientSU2 ansatz (`QuantumCircuitLibrary.circuit6`) parameterizes the trial wavefunction. Results are compared against classical NumPy diagonalization.
 
 !!! info "Data Source"
-    **JARVIS-WTB + Qiskit**
+    **JARVIS-WTB** — Wannier tight-binding Hamiltonians via `jarvis.db.figshare.get_wann_electron` / `get_wann_phonon`.
+    **Qiskit** — VQE/VQD via `jarvis.io.qiskit.inputs.HermitianSolver` (requires `qiskit==0.41.1`, `qiskit-aer`).
+
+## Available Materials
+
+| JID | Formula | Type | Qubits | Description |
+|-----|---------|------|--------|-------------|
+| JVASP-816 | Al | electron | 3 | FCC Aluminum |
+| JVASP-1002 | Si | electron | 3 | Diamond Silicon |
+| JVASP-1174 | GaAs | electron | 4 | Zinc blende GaAs |
+| JVASP-35680 | PbS | electron | 4 | Hexagonal PbS |
+| JVASP-39 | Cu | electron | 3 | FCC Copper |
+| JVASP-816 | Al | phonon | 2 | Al phonon |
+| JVASP-1002 | Si | phonon | 3 | Si phonon |
 
 ## Endpoints
 
-- `GET /quantum`
-- `GET /quantum/materials`
-- `POST /quantum/vqe`
-- `POST /quantum/bandstructure`
+### `GET /quantum/materials` — List available materials
+
+```bash
+curl "https://atomgpt.org/quantum/materials" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "accept: application/json"
+```
 
-**Request Models:** `VQERequest`, `BandstructureRequest`
+Returns `{"materials": [{"jid": "JVASP-816", "formula": "Al", "type": "electron", "qubits": 3, "desc": "FCC Aluminum"}, ...]}`.
 
-!!! note "Authentication"
-    All POST endpoints require `Authorization: Bearer YOUR_TOKEN`.
+---
 
-## API Example
+### `POST /quantum/vqe` — VQE at a single k-point
 
-```python
-import requests
-
-response = requests.post(
-    "https://atomgpt.org/quantum/vqe",
-    headers={
-        "Authorization": "Bearer sk-XYZ",
-        "accept": "application/json",
-        "Content-Type": "application/json",
-    },
-    json={"jid": "JVASP-816", "kpoint": [0.5, 0.0, 0.5], "ham_type": "electron", "reps": 2},
-)
-data = response.json()
-print(data)
+Run Qiskit VQE on the Wannier Hamiltonian H(k) at a specific k-point. Returns VQE ground-state energy, classical eigenvalues, Pauli decomposition, and circuit diagram.
+
+```bash
+curl -X POST "https://atomgpt.org/quantum/vqe" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "jid": "JVASP-816",
+    "kpoint": [0.5, 0.0, 0.5],
+    "ham_type": "electron",
+    "reps": 2,
+    "backend": "statevector_simulator"
+  }'
 ```
 
+Phonon example:
+
+```bash
+curl -X POST "https://atomgpt.org/quantum/vqe" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "jid": "JVASP-1002",
+    "kpoint": [0.0, 0.0, 0.0],
+    "ham_type": "phonon",
+    "reps": 2
+  }'
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `jid` | string | `"JVASP-816"` | JARVIS material ID |
+| `kpoint` | list[float] | `[0.5, 0.0, 0.5]` | k-point in fractional coordinates [kx, ky, kz] |
+| `ham_type` | string | `"electron"` | `"electron"` or `"phonon"` |
+| `reps` | int | 2 | EfficientSU2 circuit repetitions (1–5) |
+| `backend` | string | `"statevector_simulator"` | Qiskit Aer backend |
+
+**Response:**
+
+| Field | Description |
+|-------|-------------|
+| `vqe_ground_state` | VQE ground-state energy relative to E_F (eV) |
+| `classical_ground_state` | NumPy ground-state energy (eV) |
+| `error_eV` | Absolute error between VQE and classical |
+| `classical_eigenvalues` | All eigenvalues from NumPy (eV, relative to E_F) |
+| `n_qubits` | Number of qubits = log₂(matrix_size) |
+| `matrix_size` | Hamiltonian dimension |
+| `n_pauli_terms` | Number of Pauli operators in decomposition |
+| `n_circuit_params` | Number of variational parameters |
+| `circuit_depth` | Quantum circuit depth |
+| `circuit_diagram` | ASCII text diagram of the EfficientSU2 circuit |
+| `pauli_decomposition` | Top Pauli terms with coefficients |
+
+---
+
+### `POST /quantum/bandstructure` — Full VQD bandstructure
+
+Compute band structure across the Brillouin zone using JARVIS `get_bandstruct`. Runs VQD at each k-point along the high-symmetry path and compares with classical diagonalization.
+
+```bash
+curl -X POST "https://atomgpt.org/quantum/bandstructure" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "jid": "JVASP-816",
+    "ham_type": "electron",
+    "line_density": 3
+  }'
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `jid` | string | `"JVASP-816"` | JARVIS material ID |
+| `ham_type` | string | `"electron"` | `"electron"` or `"phonon"` |
+| `line_density` | int | 1 | K-point density along path (higher = more k-points, slower) |
+
+**Response:**
+
+| Field | Description |
+|-------|-------------|
+| `eigvals_classical` | 2D array (nkpts × nbands) from NumPy |
+| `eigvals_vqd` | 2D array (nkpts × nbands) from Qiskit VQD |
+| `n_kpoints` | Number of k-points along path |
+| `n_bands` | Number of bands |
+| `labels` | High-symmetry point labels with k-point indices |
+| `mae_eV` | Mean absolute error between VQD and classical (eV) |
+| `formula` | Chemical formula |
+
+---
+
+## Python Examples
+
+=== "VQE at single k-point"
+
+    ```python
+    import requests
+
+    response = requests.post(
+        "https://atomgpt.org/quantum/vqe",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={
+            "jid": "JVASP-816",
+            "kpoint": [0.5, 0.0, 0.5],
+            "ham_type": "electron",
+            "reps": 2,
+        },
+    )
+    data = response.json()
+    print(f"Material: {data['jid']} ({data['ham_type']})")
+    print(f"Qubits: {data['n_qubits']}, Pauli terms: {data['n_pauli_terms']}")
+    print(f"VQE ground state:      {data['vqe_ground_state']:.6f} eV")
+    print(f"Classical ground state: {data['classical_ground_state']:.6f} eV")
+    print(f"Error: {data['error_eV']:.6f} eV")
+    print(f"\nAll eigenvalues:")
+    for i, e in enumerate(data["classical_eigenvalues"]):
+        print(f"  Band {i+1}: {e:.4f} eV")
+    ```
+
+=== "Bandstructure"
+
+    ```python
+    import requests
+
+    response = requests.post(
+        "https://atomgpt.org/quantum/bandstructure",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={
+            "jid": "JVASP-816",
+            "ham_type": "electron",
+            "line_density": 3,
+        },
+    )
+    data = response.json()
+    print(f"{data['formula']} — {data['n_kpoints']} k-points, {data['n_bands']} bands")
+    print(f"MAE (VQD vs classical): {data['mae_eV']:.6f} eV")
+    print(f"Labels: {[(l['label'], l['index']) for l in data['labels']]}")
+    ```
+
+=== "Plot VQD vs classical"
+
+    ```python
+    import requests
+    import matplotlib.pyplot as plt
+    import numpy as np
+
+    response = requests.post(
+        "https://atomgpt.org/quantum/bandstructure",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "Content-Type": "application/json",
+        },
+        json={"jid": "JVASP-816", "ham_type": "electron", "line_density": 3},
+    )
+    data = response.json()
+
+    eigvals_np = np.array(data["eigvals_classical"])
+    eigvals_vqd = np.array(data["eigvals_vqd"])
+    nk = data["n_kpoints"]
+
+    fig, ax = plt.subplots(figsize=(8, 5))
+    for b in range(eigvals_np.shape[1]):
+        ax.plot(range(nk), eigvals_np[:, b], "b-", lw=1.5,
+                label="Classical" if b == 0 else "")
+        ax.plot(range(nk), eigvals_vqd[:, b], "ro", ms=3, alpha=0.7,
+                label="VQD" if b == 0 else "")
+
+    for lbl in data["labels"]:
+        ax.axvline(lbl["index"], color="gray", ls="--", lw=0.5)
+        ax.text(lbl["index"], ax.get_ylim()[0], lbl["label"],
+                ha="center", va="top", fontsize=9)
+
+    ax.set_ylabel("Energy (eV)")
+    ax.set_title(f"{data['formula']} — MAE: {data['mae_eV']:.4f} eV")
+    ax.legend()
+    plt.tight_layout()
+    plt.savefig("quantum_bands.png", dpi=150)
+    ```
+
 ## AGAPI Agent
 
 ```python
@@ -54,10 +242,19 @@ from agapi.agents import AGAPIAgent
 import os
 
 agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
-response = agent.query_sync("Show quantum computation for Silicon")
+
+# VQE
+response = agent.query_sync("Run VQE for Al at the X point using quantum computation")
+print(response)
+
+# Bandstructure
+response = agent.query_sync("Compute quantum bandstructure for Si using VQD")
 print(response)
 ```
 
-## Reference
+## References
 
-- J. Phys.: Condens. Matter 33, 385501 (2021)
+- K. Choudhary, J. Phys.: Condens. Matter 33, 385501 (2021) [:material-link: DOI](https://doi.org/10.1088/1361-648X/ac1154)
+- BenchQC (2025) [:material-link: DOI](https://arxiv.org/abs/2502.09595)
+- K. Choudhary, Comp. Mat. Sci. 259, 114063 (2025) [:material-link: DOI](https://doi.org/10.1016/j.commatsci.2025.114063)
+- [atomgptlab/jarvis](https://github.com/atomgptlab/jarvis)
diff --git a/docs/apps/predict/slakonet.md b/docs/apps/predict/slakonet.md
index 5e683db..9a50634 100644
--- a/docs/apps/predict/slakonet.md
+++ b/docs/apps/predict/slakonet.md
@@ -4,7 +4,7 @@ title: SlakoNet Bands
 
 # SlakoNet Bands
 
-Deep learning tight-binding band structures from neural network Slater-Koster parameters. Query by JARVIS ID or upload POSCAR. Web analyze endpoint returns band structure + DOS.
+Deep learning tight-binding electronic structure calculator. Three tabs: (1) Band Structure + DOS — high-symmetry path band diagram with atom-projected DOS, (2) 3D Band Surface — interactive kx-ky energy surface with BZ overlay and Fermi plane, (3) Fermi Surface — 2D contour plots, 3D near-Fermi bands, and true 3D Fermi isosurfaces via marching cubes. All powered by SlakoNet neural network Slater-Koster parameters.
 
 [:material-open-in-new: Open App](https://atomgpt.org/slakonet){ .md-button .md-button--primary }
 
@@ -12,41 +12,224 @@ Deep learning tight-binding band structures from neural network Slater-Koster pa
 
 ## Overview
 
-Deep learning tight-binding band structures from neural network Slater-Koster parameters. Query by JARVIS ID or upload POSCAR. Web analyze endpoint returns band structure + DOS.
+SlakoNet predicts Slater-Koster tight-binding parameters using a deep learning model, enabling rapid electronic band structure and density of states calculations without DFT. The model supports elements up to Z=85 and handles multi-element systems. Max 50 atoms for band structure, max 20 atoms for 3D Fermi isosurface (due to N³ k-mesh cost).
 
 !!! info "Data Source"
-    **SlakoNet pretrained model**
+    **SlakoNet** pretrained model — neural network Slater-Koster parameters from `slakonet.predict_slakonet`.
 
 ## Endpoints
 
-- `GET /slakonet`
-- `GET /slakonet/bandstructure`
-- `POST /slakonet/bandstructure`
-- `POST /slakonet/web_analyze`
+### `GET /slakonet/bandstructure` — Band structure image (API key)
 
-**Request Models:** —
+Returns a PNG image of the band structure + DOS along the high-symmetry path. Band gap, VBM, and CBM are in response headers.
 
-!!! note "Authentication"
-    All POST endpoints require `Authorization: Bearer YOUR_TOKEN`.
+```bash
+curl "https://atomgpt.org/slakonet/bandstructure?jid=JVASP-1002&energy_range_min=-8&energy_range_max=8&APIKEY=sk-XYZ" \
+  --output bandstructure_Si.png
+```
 
-## API Example
+With POSCAR string:
 
-```python
-import requests
-
-response = requests.post(
-    "https://atomgpt.org/slakonet/bandstructure",
-    headers={
-        "Authorization": "Bearer sk-XYZ",
-        "accept": "application/json",
-        "Content-Type": "application/json",
-    },
-    json={"jid": "JVASP-1002"},
-)
-data = response.json()
-print(data)
+```bash
+curl "https://atomgpt.org/slakonet/bandstructure?poscar=MgB2%0A1.0%0A1.537%20-2.662%200.0%0A1.537%202.662%200.0%0A0.0%200.0%203.515%0AMg%20B%0A1%202%0ACartesian%0A0.0%200.0%200.0%0A1.537%20-0.887%201.757%0A1.537%200.887%201.757&APIKEY=sk-XYZ" \
+  --output bandstructure_MgB2.png
 ```
 
+| Param | Description |
+|-------|-------------|
+| `jid` | JARVIS ID — provide `jid` OR `poscar` |
+| `poscar` | URL-encoded POSCAR string |
+| `energy_range_min` | Energy axis min (default -8 eV) |
+| `energy_range_max` | Energy axis max (default 8 eV) |
+| `APIKEY` | API key |
+
+Returns `image/png` with headers: `X-Band-Gap`, `X-VBM`, `X-CBM`, `X-Formula`.
+
+---
+
+### `POST /slakonet/web_analyze` — Band structure + DOS (JSON)
+
+Returns band gap, VBM, CBM, base64 plot, and full band data (eigenvalues, DOS, atom-projected DOS) as JSON.
+
+```bash
+curl -X POST "https://atomgpt.org/slakonet/web_analyze" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "poscar": "MgB2\n1.0\n1.537 -2.662 0.0\n1.537 2.662 0.0\n0.0 0.0 3.515\nMg B\n1 2\nCartesian\n0.0 0.0 0.0\n1.537 -0.887 1.757\n1.537 0.887 1.757",
+    "energy_range_min": -8,
+    "energy_range_max": 8
+  }'
+```
+
+**Response** includes `band_gap`, `vbm`, `cbm`, `plot_base64` (PNG), `formula`, `num_atoms`, and `band_data` (eigenvalues, dos_energies, dos_values, atom_pdos).
+
+---
+
+### `POST /slakonet/bandstructure3d` — 3D band surface (kx-ky plane)
+
+Compute band energies on a 2D Cartesian k-mesh at kz=0 for interactive 3D Plotly surface plots.
+
+```bash
+curl -X POST "https://atomgpt.org/slakonet/bandstructure3d" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "poscar": "MgB2\n1.0\n1.537 -2.662 0.0\n1.537 2.662 0.0\n0.0 0.0 3.515\nMg B\n1 2\nCartesian\n0.0 0.0 0.0\n1.537 -0.887 1.757\n1.537 0.887 1.757",
+    "nk_per_dim": 30
+  }'
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `poscar` | string | required | POSCAR (max 50 atoms) |
+| `nk_per_dim` | int | 30 | k-points per axis (10–60) |
+
+**Response** includes `kx_grid`, `ky_grid`, `bands` (one 2D array per band), `bz_x`/`bz_y` (BZ outline), `bandgap`, `nbands`.
+
+---
+
+### `POST /slakonet/fermisurface` — 2D Fermi surface
+
+Compute 2D Fermi contours at kz=0. Returns band energies on k-mesh, Fermi-crossing band indices, BZ outline, and high-symmetry point coordinates (Γ, K, K', M).
+
+```bash
+curl -X POST "https://atomgpt.org/slakonet/fermisurface" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "poscar": "MgB2\n1.0\n1.537 -2.662 0.0\n1.537 2.662 0.0\n0.0 0.0 3.515\nMg B\n1 2\nCartesian\n0.0 0.0 0.0\n1.537 -0.887 1.757\n1.537 0.887 1.757",
+    "nk_per_dim": 40,
+    "energy_window": 0.5
+  }'
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `poscar` | string | required | POSCAR (max 50 atoms) |
+| `nk_per_dim` | int | 40 | k-points per axis (10–60) |
+| `energy_window` | float | 0.5 | Energy window around E_F for identifying Fermi bands (eV) |
+
+**Response** includes `fermi_bands` (indices), `band_info` (per-band min/max/crosses_ef), `kx_1d`/`ky_1d`/`kx_grid`/`ky_grid`, `bands`, `high_sym` (Γ/K/K'/M coordinates).
+
+---
+
+### `POST /slakonet/fermisurface3d` — 3D Fermi isosurface (marching cubes)
+
+Compute a true 3D Fermi isosurface on a full kx-ky-kz mesh using marching cubes (`skimage.measure.marching_cubes`). Returns mesh vertices and faces for Plotly Mesh3d rendering. Computationally heavy — max 20 atoms, max 35³ k-points.
+
+```bash
+curl -X POST "https://atomgpt.org/slakonet/fermisurface3d" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "poscar": "MgB2\n1.0\n1.537 -2.662 0.0\n1.537 2.662 0.0\n0.0 0.0 3.515\nMg B\n1 2\nCartesian\n0.0 0.0 0.0\n1.537 -0.887 1.757\n1.537 0.887 1.757",
+    "nk_per_dim": 20,
+    "energy_window": 0.5
+  }'
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `poscar` | string | required | POSCAR (max **20** atoms) |
+| `nk_per_dim` | int | 20 | k-points per axis (8–35, i.e. max 35³ = 42,875 k-points) |
+| `energy_window` | float | 0.5 | Energy window for Fermi band identification (eV) |
+
+**Response** includes `meshes` (per-band: `vertices_x/y/z`, `faces_i/j/k` for Mesh3d), `fermi_bands`, `band_info`, `bz_x`/`bz_y`.
+
+---
+
+## Python Examples
+
+=== "Band structure by JID"
+
+    ```python
+    import requests
+
+    response = requests.get(
+        "https://atomgpt.org/slakonet/bandstructure",
+        headers={"accept": "image/png"},
+        params={
+            "jid": "JVASP-1002",
+            "energy_range_min": -8,
+            "energy_range_max": 8,
+            "APIKEY": "sk-XYZ",
+        },
+    )
+    with open("bandstructure_Si.png", "wb") as f:
+        f.write(response.content)
+    print(f"Band gap: {response.headers.get('X-Band-Gap')} eV")
+    ```
+
+=== "Web analyze (JSON)"
+
+    ```python
+    import requests
+
+    response = requests.post(
+        "https://atomgpt.org/slakonet/web_analyze",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "Content-Type": "application/json",
+        },
+        json={"poscar": open("POSCAR").read()},
+    )
+    data = response.json()
+    print(f"Band gap: {data['band_gap']:.3f} eV")
+    print(f"VBM: {data['vbm']:.3f}, CBM: {data['cbm']:.3f} eV")
+
+    # Save plot
+    import base64
+    with open("bands.png", "wb") as f:
+        f.write(base64.b64decode(data["plot_base64"]))
+    ```
+
+=== "3D band surface"
+
+    ```python
+    import requests
+
+    response = requests.post(
+        "https://atomgpt.org/slakonet/bandstructure3d",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "Content-Type": "application/json",
+        },
+        json={"poscar": open("POSCAR").read(), "nk_per_dim": 30},
+    )
+    data = response.json()
+    print(f"Bands: {data['nbands']}, Gap: {data['bandgap']:.3f} eV")
+    print(f"K-mesh: {data['nk']}×{data['nky']}")
+    ```
+
+=== "Fermi surface"
+
+    ```python
+    import requests
+
+    response = requests.post(
+        "https://atomgpt.org/slakonet/fermisurface",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "Content-Type": "application/json",
+        },
+        json={
+            "poscar": open("MgB2.vasp").read(),
+            "nk_per_dim": 40,
+            "energy_window": 0.5,
+        },
+    )
+    data = response.json()
+    print(f"Fermi bands: {data['fermi_bands']}")
+    print(f"Band gap: {data['bandgap']:.3f} eV")
+    hs = data["high_sym"]
+    print(f"Γ={hs['Gamma']}, K={hs['K']}, M={hs['M']}")
+    ```
+
 ## AGAPI Agent
 
 ```python
@@ -54,10 +237,18 @@ from agapi.agents import AGAPIAgent
 import os
 
 agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
-response = agent.query_sync("Show slakonet bands for Silicon")
+
+# Band structure
+response = agent.query_sync("Compute the SlakoNet band structure for MgB2")
+print(response)
+
+# Fermi surface
+response = agent.query_sync("Show the Fermi surface of MgB2 using SlakoNet")
 print(response)
 ```
 
-## Reference
+## References
 
-- J. Phys. Chem. Lett. 16, 11109 (2025)
+- K. Choudhary, J. Phys. Chem. Lett. 16, 11109 (2025) — SlakoNet [:material-link: DOI](https://doi.org/10.1021/acs.jpclett.5c02456)
+- K. Choudhary, Comp. Mat. Sci. 259, 114063 (2025) [:material-link: DOI](https://doi.org/10.1016/j.commatsci.2025.114063)
+- [atomgptlab/slakonet](https://github.com/atomgptlab/slakonet)
diff --git a/docs/apps/predict/wtb.md b/docs/apps/predict/wtb.md
index f63a9ff..3dd15a1 100644
--- a/docs/apps/predict/wtb.md
+++ b/docs/apps/predict/wtb.md
@@ -4,7 +4,7 @@ title: Wannier TB Bands
 
 # Wannier TB Bands
 
-Wannier tight-binding Hamiltonian bandstructure and DOS. Selects material by JID from JARVIS-WTB database, downloads wannier90_hr.dat, computes band structure and DOS.
+Compute electronic band structures and density of states from Wannier tight-binding Hamiltonians in the JARVIS-WTB database. Select a material by JARVIS ID, provide a VASP-format k-point path, and the app downloads the `wannier90_hr.dat` from figshare, diagonalizes the Hamiltonian along the k-path using `jarvis.io.wannier.outputs.WannierHam`, and returns eigenvalues + DOS.
 
 [:material-open-in-new: Open App](https://atomgpt.org/wtb){ .md-button .md-button--primary }
 
@@ -12,40 +12,179 @@ Wannier tight-binding Hamiltonian bandstructure and DOS. Selects material by JID
 
 ## Overview
 
-Wannier tight-binding Hamiltonian bandstructure and DOS. Selects material by JID from JARVIS-WTB database, downloads wannier90_hr.dat, computes band structure and DOS.
+The JARVIS-WTB database contains Wannier90 tight-binding Hamiltonians for thousands of materials, enabling rapid band structure calculations without re-running DFT. The app downloads the compressed `wannier90_hr.dat` file, parses it with `WannierHam`, computes eigenvalues along a user-specified k-path, and calculates DOS with Gaussian broadening (σ=0.1, 1000 energy points). Results include Wannier function count, Fermi energy, and DFT-vs-Wannier interpolation errors (`maxdiff_bz`, `maxdiff_mesh`).
 
 !!! info "Data Source"
-    **JARVIS-WTB (wannier90_hr.dat files)**
+    **JARVIS-WTB** — `wannier90_hr.dat` files from `jarvis.db.figshare.data('raw_files')['WANN']`.
+    Material metadata from `all_wanns.json` (formula, space group, Fermi energy, interpolation errors).
 
 ## Endpoints
 
-- `GET /wtb`
-- `GET /wtb/options`
-- `POST /wtb/predict`
+### `GET /wtb/options` — List available WTB materials
 
-**Request Models:** `WtbPredictRequest`
+Returns a dropdown list of all materials in the JARVIS-WTB database with JID, formula, and space group.
 
-!!! note "Authentication"
-    All POST endpoints require `Authorization: Bearer YOUR_TOKEN`.
+```bash
+curl "https://atomgpt.org/wtb/options" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "accept: application/json"
+```
 
-## API Example
+**Response:** `{"success": true, "options": [{"jid": "JVASP-1002", "formula": "Si", "spg": "Fd-3m"}, ...]}`
 
-```python
-import requests
-
-response = requests.post(
-    "https://atomgpt.org/wtb/predict",
-    headers={
-        "Authorization": "Bearer sk-XYZ",
-        "accept": "application/json",
-        "Content-Type": "application/json",
-    },
-    json={"jid": "JVASP-1002"},
-)
-data = response.json()
-print(data)
+---
+
+### `POST /wtb/predict` — Compute bandstructure + DOS
+
+Select a material by JID and provide a VASP line-mode KPOINTS path. Downloads the Wannier Hamiltonian and computes eigenvalues + DOS.
+
+```bash
+curl -X POST "https://atomgpt.org/wtb/predict" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "jid": "JVASP-1002",
+    "kpoints": "Line mode\n40\nReciprocal\n0.5 0.5 0.5 L\n0.0 0.0 0.0 \\Gamma\n\n0.0 0.0 0.0 \\Gamma\n0.5 0.0 0.5 X\n\n0.5 0.0 0.5 X\n0.5 0.25 0.75 W\n\n0.5 0.25 0.75 W\n0.375 0.375 0.75 K"
+  }'
 ```
 
+BCC k-path example:
+
+```bash
+curl -X POST "https://atomgpt.org/wtb/predict" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -H "Content-Type: application/json" \
+  -H "accept: application/json" \
+  -d '{
+    "jid": "JVASP-816",
+    "kpoints": "Line mode\n40\nReciprocal\n0.0 0.0 0.0 \\Gamma\n0.5 -0.5 0.5 H\n\n0.5 -0.5 0.5 H\n0.25 0.25 0.25 P\n\n0.25 0.25 0.25 P\n0.0 0.0 0.0 \\Gamma\n\n0.0 0.0 0.0 \\Gamma\n0.0 0.0 0.5 N"
+  }'
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `jid` | string | JARVIS ID from the WTB database (use `/wtb/options` to list) |
+| `kpoints` | string | VASP line-mode KPOINTS format (pairs of k-points with labels) |
+
+**Response:**
+
+| Field | Description |
+|-------|-------------|
+| `bands` | 2D array (nbands × nkpts) of eigenvalues (eV, relative to E_F) |
+| `nkpts` | Number of k-points along the path |
+| `kp_labels_points` | k-point indices where labels appear |
+| `kp_labels_text` | High-symmetry point labels (Γ, X, W, K, etc.) |
+| `en_dos` | DOS energy grid (eV) |
+| `dos` | DOS values |
+| `formula` | Chemical formula |
+| `spg` | Space group |
+| `efermi` | Fermi energy (eV) |
+| `nwan` | Number of Wannier functions |
+| `maxdiff_bz` | Max DFT-vs-Wannier error along BZ path (eV) |
+| `maxdiff_mesh` | Max DFT-vs-Wannier error on k-mesh (eV) |
+| `total_time` | Computation time (seconds) |
+| `download_url` | Direct download URL for the wannier90_hr.dat.zip |
+
+---
+
+## Python Examples
+
+=== "Compute bandstructure"
+
+    ```python
+    import requests
+
+    FCC_KPOINTS = """Line mode
+    40
+    Reciprocal
+    0.5 0.5 0.5 L
+    0.0 0.0 0.0 \\Gamma
+
+    0.0 0.0 0.0 \\Gamma
+    0.5 0.0 0.5 X
+
+    0.5 0.0 0.5 X
+    0.5 0.25 0.75 W
+
+    0.5 0.25 0.75 W
+    0.375 0.375 0.75 K"""
+
+    response = requests.post(
+        "https://atomgpt.org/wtb/predict",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={"jid": "JVASP-1002", "kpoints": FCC_KPOINTS},
+    )
+    data = response.json()
+    if data["success"]:
+        print(f"{data['formula']} ({data['spg']})")
+        print(f"  Wannier functions: {data['nwan']}")
+        print(f"  Fermi energy: {data['efermi']:.3f} eV")
+        print(f"  Bands: {len(data['bands'])}, K-points: {data['nkpts']}")
+        print(f"  Maxdiff BZ: {data['maxdiff_bz']} eV")
+        print(f"  Time: {data['total_time']}s")
+    ```
+
+=== "Plot bandstructure"
+
+    ```python
+    import requests
+    import matplotlib.pyplot as plt
+
+    response = requests.post(
+        "https://atomgpt.org/wtb/predict",
+        headers={
+            "Authorization": "Bearer sk-XYZ",
+            "accept": "application/json",
+            "Content-Type": "application/json",
+        },
+        json={"jid": "JVASP-1002", "kpoints": open("KPOINTS").read()},
+    )
+    data = response.json()
+
+    fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(12, 5), gridspec_kw={"width_ratios": [3, 1]})
+
+    # Band structure
+    for band in data["bands"]:
+        ax1.plot(range(data["nkpts"]), band, "b-", lw=0.8)
+    ax1.axhline(0, color="gray", ls="--", lw=0.5)
+    ax1.set_xticks(data["kp_labels_points"])
+    ax1.set_xticklabels(data["kp_labels_text"])
+    ax1.set_ylabel("E - E_F (eV)")
+    ax1.set_ylim(-4, 4)
+    ax1.set_title(f"{data['formula']} ({data['spg']})")
+
+    # DOS
+    ax2.plot(data["dos"], data["en_dos"], "b-", lw=1.5)
+    ax2.fill_betweenx(data["en_dos"], 0, data["dos"], alpha=0.15)
+    ax2.axhline(0, color="gray", ls="--", lw=0.5)
+    ax2.set_xlabel("DOS")
+    ax2.set_ylim(-4, 4)
+    ax2.set_yticklabels([])
+
+    plt.tight_layout()
+    plt.savefig(f"wtb_{data['jid']}.png", dpi=150)
+    ```
+
+=== "List available materials"
+
+    ```python
+    import requests
+
+    response = requests.get(
+        "https://atomgpt.org/wtb/options",
+        headers={"Authorization": "Bearer sk-XYZ"},
+    )
+    data = response.json()
+    print(f"Total WTB materials: {len(data['options'])}")
+    for opt in data["options"][:10]:
+        print(f"  {opt['jid']:12s} {opt['formula']:10s} {opt['spg']}")
+    ```
+
 ## AGAPI Agent
 
 ```python
@@ -53,10 +192,14 @@ from agapi.agents import AGAPIAgent
 import os
 
 agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
-response = agent.query_sync("Show wannier tb bands for Silicon")
+
+# Compute band structure
+response = agent.query_sync("Compute Wannier TB bandstructure for Si (JVASP-1002)")
 print(response)
 ```
 
-## Reference
+## References
 
-- Sci. Data 8, 106 (2021)
+- K. Choudhary et al., Sci. Data 8, 106 (2021) — JARVIS-WTB [:material-link: DOI](https://doi.org/10.1038/s41597-021-00885-z)
+- K. Choudhary et al., npj Comp. Mat. 6, 173 (2020) [:material-link: DOI](https://doi.org/10.1038/s41524-020-00440-1)
+- [atomgptlab/jarvis](https://github.com/atomgptlab/jarvis)
diff --git a/docs/apps/validate/ai-detector.md b/docs/apps/validate/ai-detector.md
index f261c5d..d8f6980 100644
--- a/docs/apps/validate/ai-detector.md
+++ b/docs/apps/validate/ai-detector.md
@@ -4,7 +4,7 @@ title: AI Detector
 
 # AI Detector
 
-AI-generated text detector. Hybrid approach: statistical analysis (perplexity, burstiness, entropy variance, sentence length) + LLM judge. Scans text and returns confidence scores.
+Detect AI-generated text using a hybrid approach: statistical analysis (sentence uniformity, vocabulary repetition, AI marker phrases, punctuation diversity) combined with an LLM judge for style classification. Supports text input or PDF/TXT file upload.
 
 [:material-open-in-new: Open App](https://atomgpt.org/ai_detector){ .md-button .md-button--primary }
 
@@ -12,50 +12,131 @@ AI-generated text detector. Hybrid approach: statistical analysis (perplexity, b
 
 ## Overview
 
-AI-generated text detector. Hybrid approach: statistical analysis (perplexity, burstiness, entropy variance, sentence length) + LLM judge. Scans text and returns confidence scores.
+The AI Detector computes 6 statistical signals that distinguish AI-generated text from human writing, then optionally asks an LLM to analyze writing style. The final score is a weighted combination (60% LLM + 40% statistical when LLM is enabled). Verdicts range from "human" to "ai" based on the combined probability.
+
+**Statistical signals:** burstiness (sentence length variance), vocabulary richness (type-token ratio), word formality (avg word length), sentence starter diversity, AI marker phrase density, punctuation diversity.
 
 !!! info "Data Source"
-    **Statistical analysis + LLM judge**
+    **Statistical analysis** — built-in heuristics.
+    **LLM judge** — configurable LLM backend for style classification.
 
 ## Endpoints
 
-- `GET /ai_detector`
-- `POST /ai_detector/scan`
+### `POST /ai_detector/scan` — Scan text for AI content
 
-**Request Models:** —
+Upload text or a file (PDF/TXT) for AI detection. Uses multipart form data.
 
-!!! note "Authentication"
-    All POST endpoints require `Authorization: Bearer YOUR_TOKEN`.
+```bash
+curl -X POST "https://atomgpt.org/ai_detector/scan" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -F "text=Artificial intelligence has become an increasingly important tool in modern scientific research. It is worth noting that machine learning methods have shown remarkable potential in materials discovery. Furthermore, the integration of large language models into scientific workflows represents a groundbreaking development." \
+  -F "use_llm=true"
+```
 
-## API Example
+Scan without LLM (statistical only, faster):
 
-```python
-import requests
-
-response = requests.post(
-    "https://atomgpt.org/ai_detector/scan",
-    headers={
-        "Authorization": "Bearer sk-XYZ",
-        "accept": "application/json",
-        "Content-Type": "application/json",
-    },
-    json={"text": "Sample text to analyze"},
-)
-data = response.json()
-print(data)
+```bash
+curl -X POST "https://atomgpt.org/ai_detector/scan" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -F "text=So I was trying to get ALIGNN to work on my perovskite dataset and it kept crashing. Turns out I had NaN values in 3 of my structures. Took me two days to figure that out!" \
+  -F "use_llm=false"
 ```
 
-## AGAPI Agent
+Scan a PDF file:
+
+```bash
+curl -X POST "https://atomgpt.org/ai_detector/scan" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -F "file=@paper.pdf" \
+  -F "use_llm=true"
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `text` | string | — | Text to analyze (provide `text` or `file`) |
+| `file` | file | — | PDF or TXT file to analyze |
+| `use_llm` | string | `"true"` | Use LLM judge (`"true"` or `"false"`) |
+
+**Response** is streamed as NDJSON (`application/x-ndjson`) with progressive updates:
+
+1. `{"type": "status", "message": "Running statistical analysis..."}`
+2. `{"type": "stats", "data": {...}}` — statistical scores
+3. `{"type": "status", "message": "Running LLM analysis..."}` (if use_llm)
+4. `{"type": "llm", "data": {...}}` — LLM verdict (if use_llm)
+5. `{"type": "result", ...}` — final combined result
+
+**Final result fields:**
+
+| Field | Description |
+|-------|-------------|
+| `ai_probability` | Combined AI probability (0–100%) |
+| `verdict` | `"human"`, `"likely_human"`, `"mixed"`, `"likely_ai"`, or `"ai"` |
+| `stat_probability` | Statistical-only AI probability |
+| `llm_probability` | LLM-only AI probability (null if disabled) |
+| `statistical.scores` | Per-signal breakdown (burstiness, vocabulary, word_length, sentence_starters, ai_phrases, punctuation) |
+| `llm_judge.reasoning` | LLM explanation |
+| `llm_judge.signals` | Per-signal indicators from LLM |
+
+---
+
+## Python Examples
+
+=== "Scan text"
+
+    ```python
+    import requests
+
+    response = requests.post(
+        "https://atomgpt.org/ai_detector/scan",
+        headers={"Authorization": "Bearer sk-XYZ"},
+        data={
+            "text": "It is important to note that machine learning has shown remarkable potential...",
+            "use_llm": "true",
+        },
+    )
+    # Parse NDJSON stream
+    for line in response.text.strip().split("\n"):
+        if line.strip():
+            import json
+            chunk = json.loads(line)
+            if chunk.get("type") == "result":
+                print(f"Verdict: {chunk['verdict']}")
+                print(f"AI probability: {chunk['ai_probability']}%")
+                print(f"  Statistical: {chunk['stat_probability']}%")
+                print(f"  LLM: {chunk.get('llm_probability', 'N/A')}%")
+    ```
+
+=== "Scan PDF"
+
+    ```python
+    import requests
+
+    with open("paper.pdf", "rb") as f:
+        response = requests.post(
+            "https://atomgpt.org/ai_detector/scan",
+            headers={"Authorization": "Bearer sk-XYZ"},
+            files={"file": ("paper.pdf", f, "application/pdf")},
+            data={"use_llm": "true"},
+        )
+    import json
+    for line in response.text.strip().split("\n"):
+        if line.strip():
+            chunk = json.loads(line)
+            if chunk.get("type") == "result":
+                print(f"Verdict: {chunk['verdict']} ({chunk['ai_probability']}%)")
+    ```
+
+## AGAPI Agent [WIP]
 
 ```python
 from agapi.agents import AGAPIAgent
 import os
 
 agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
-response = agent.query_sync("Show ai detector for Silicon")
+response = agent.query_sync("Check if this text is AI-generated: Furthermore, it is essential to note...")
 print(response)
 ```
 
-## Reference
+## References
 
-- —
+- [atomgptlab](https://github.com/atomgptlab)
diff --git a/docs/apps/validate/hallucination.md b/docs/apps/validate/hallucination.md
index debe97f..82dce3d 100644
--- a/docs/apps/validate/hallucination.md
+++ b/docs/apps/validate/hallucination.md
@@ -4,7 +4,7 @@ title: Hallucination Detector
 
 # Hallucination Detector
 
-Verify LLM outputs against JARVIS data. Cross-check predicted properties and material claims with the DFT database. Streaming check endpoint for real-time verification.
+Verify academic references in LLM-generated text against Semantic Scholar. Extracts references using LLM-based structured extraction (with regex fallback), then checks each title against the Semantic Scholar API with composite scoring: 60% title fuzzy match + 25% author match + 15% journal match. Supports text input or PDF upload. Results stream progressively as each reference is verified.
 
 [:material-open-in-new: Open App](https://atomgpt.org/hallucination_detector){ .md-button .md-button--primary }
 
@@ -12,51 +12,211 @@ Verify LLM outputs against JARVIS data. Cross-check predicted properties and mat
 
 ## Overview
 
-Verify LLM outputs against JARVIS data. Cross-check predicted properties and material claims with the DFT database. Streaming check endpoint for real-time verification.
+The Hallucination Detector addresses fabricated academic references in LLM-generated text. The pipeline is: (1) extract references from the bibliography section using an LLM (OpenAI SDK with structured JSON extraction), falling back to regex parsing if LLM fails; (2) for each reference, search Semantic Scholar's paper search API; (3) compute a composite verification score using rapidfuzz token_set_ratio on title, author last-name matching, and journal/venue matching; (4) classify as "verified" (≥threshold), "partial" (≥60), or "likely hallucinated" (<60).
 
 !!! info "Data Source"
-    **dft_3d + LLM verification**
+    **Semantic Scholar API** — `api.semanticscholar.org/graph/v1/paper/search` for paper verification.
+    **LLM** — OpenAI-compatible endpoint for structured reference extraction.
+    **rapidfuzz** — `token_set_ratio` for fuzzy title/journal matching.
 
 ## Endpoints
 
-- `GET /hallucination_detector`
-- `GET /detector`
-- `POST /hallucination/check_stream`
+### `POST /hallucination/check_stream` — Verify references in text
 
-**Request Models:** —
+Upload text or a PDF containing academic references. The detector extracts references, then verifies each against Semantic Scholar. Results stream as NDJSON with a configurable delay between API calls.
 
-!!! note "Authentication"
-    All POST endpoints require `Authorization: Bearer YOUR_TOKEN`.
+```bash
+curl -X POST "https://atomgpt.org/hallucination/check_stream" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -F 'text=This paper discusses materials discovery using AI.
 
-## API Example
+References
+[1] Kamal Choudhary, Brian DeCost, and Francesca Tavazza. Benchmarking graph neural networks for materials chemistry. npj Computational Materials, 6(1), 2020.
+[2] Kamal Choudhary. AtomGPT: Atomistic generative pretrained transformer for forward and inverse materials design. The Journal of Physical Chemistry Letters, 15(27):6909-6917, 2024.
+[3] Fake Q. Author. Quantum blockchain neural networks for perpetual motion machines. Nature of Nonsense, 99:1-99, 2099.' \
+  -F "top_k=5" \
+  -F "threshold=80" \
+  -F "sleep_sec=2.0"
+```
 
-```python
-import requests
-
-response = requests.post(
-    "https://atomgpt.org/hallucination/check_stream",
-    headers={
-        "Authorization": "Bearer sk-XYZ",
-        "accept": "application/json",
-        "Content-Type": "application/json",
-    },
-    json={"jid": "JVASP-1002"},
-)
-data = response.json()
-print(data)
+Verify a PDF:
+
+```bash
+curl -X POST "https://atomgpt.org/hallucination/check_stream" \
+  -H "Authorization: Bearer sk-XYZ" \
+  -F "file=@paper.pdf" \
+  -F "top_k=5" \
+  -F "threshold=80"
 ```
 
-## AGAPI Agent
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `text` | string | — | Text with references section (provide `text` or `file`) |
+| `file` | file | — | PDF file to extract and verify |
+| `ss_api_key` | string | `""` | Optional Semantic Scholar API key (built-in key used by default) |
+| `top_k` | int | 5 | Number of Semantic Scholar results to check per reference (1–20) |
+| `threshold` | int | 80 | Composite score threshold for "verified" status (30–100) |
+| `sleep_sec` | float | 2.0 | Delay between Semantic Scholar queries to avoid rate limiting (1–60) |
+
+**Response** is streamed as NDJSON (`application/x-ndjson`) with progressive updates:
+
+1. `{"type": "extracting", "message": "Extracting references..."}`
+2. `{"type": "total", "total": N, "method_used": "llm"}` — extraction complete
+3. `{"type": "checking", "index": i, "total": N, "title_guess": "..."}` — per-reference progress
+4. `{"type": "result", "index": i, ...}` — per-reference verification result
+5. `{"type": "done", "total": N, "method_used": "llm"}` — all checks complete
+
+**Per-reference result fields:**
+
+| Field | Description |
+|-------|-------------|
+| `status` | `"verified"` (score ≥ threshold), `"partial"` (≥ 60), or `"likely hallucinated"` (< 60) |
+| `score` | Composite score (0–100): 60% title + 25% author + 15% journal |
+| `title_score` | Fuzzy title match score alone |
+| `author_score` | Author last-name match percentage (null if no authors extracted) |
+| `journal_score` | Journal/venue fuzzy match (null if no journal extracted) |
+| `year_match` | `true`/`false`/`null` — whether extracted year matches |
+| `best_match` | Best matching paper title from Semantic Scholar |
+| `matched_authors` | Author names from the matched paper |
+| `matched_venue` | Journal/venue from the matched paper |
+| `matched_year` | Publication year from the matched paper |
+| `total_hits` | Total Semantic Scholar search results |
+| `query` | Cleaned search query sent to Semantic Scholar |
+| `reference` | Original extracted reference text |
+
+---
+
+## Python Examples
+
+=== "Verify references"
+
+    ```python
+    import requests
+    import json
+
+    TEXT = """
+    This paper builds on prior work in materials AI.
+
+    References
+    [1] Kamal Choudhary et al. The joint automated repository for various
+        integrated simulations (JARVIS). npj Computational Materials, 6, 173, 2020.
+    [2] Fake Q. Author. Quantum blockchain for perpetual motion. Nature of
+        Nonsense, 99:1-99, 2099.
+    """
+
+    response = requests.post(
+        "https://atomgpt.org/hallucination/check_stream",
+        headers={"Authorization": "Bearer sk-XYZ"},
+        data={
+            "text": TEXT,
+            "top_k": "5",
+            "threshold": "80",
+            "sleep_sec": "2.0",
+        },
+        stream=True,
+    )
+
+    verified, flagged = 0, 0
+    for line in response.iter_lines():
+        if not line:
+            continue
+        chunk = json.loads(line)
+        if chunk["type"] == "result":
+            status = chunk["status"]
+            icon = "✓" if status == "verified" else "~" if status == "partial" else "✗"
+            print(f"  {icon} [{chunk['score']:.0f}%] {chunk['reference'][:60]}")
+            print(f"     → {chunk['best_match'][:60]}")
+            if status == "verified":
+                verified += 1
+            else:
+                flagged += 1
+        elif chunk["type"] == "done":
+            print(f"\nTotal: {chunk['total']}, Verified: {verified}, Flagged: {flagged}")
+    ```
+
+=== "Verify PDF"
+
+    ```python
+    import requests
+    import json
+
+    with open("paper.pdf", "rb") as f:
+        response = requests.post(
+            "https://atomgpt.org/hallucination/check_stream",
+            headers={"Authorization": "Bearer sk-XYZ"},
+            files={"file": ("paper.pdf", f, "application/pdf")},
+            data={"threshold": "75"},
+            stream=True,
+        )
+
+    hallucinated = []
+    for line in response.iter_lines():
+        if not line:
+            continue
+        chunk = json.loads(line)
+        if chunk["type"] == "result" and chunk["status"] == "likely hallucinated":
+            hallucinated.append({
+                "ref": chunk["reference"][:80],
+                "score": chunk["score"],
+                "best_match": chunk["best_match"][:60],
+            })
+
+    if hallucinated:
+        print(f"Found {len(hallucinated)} potentially hallucinated references:")
+        for h in hallucinated:
+            print(f"  ✗ [{h['score']:.0f}%] {h['ref']}")
+            print(f"     Best match: {h['best_match']}")
+    else:
+        print("All references verified!")
+    ```
+
+=== "Batch check files"
+
+    ```python
+    import requests
+    import json
+    import glob
+
+    for pdf_path in glob.glob("papers/*.pdf"):
+        with open(pdf_path, "rb") as f:
+            response = requests.post(
+                "https://atomgpt.org/hallucination/check_stream",
+                headers={"Authorization": "Bearer sk-XYZ"},
+                files={"file": (pdf_path, f, "application/pdf")},
+                data={"threshold": "80"},
+                stream=True,
+            )
+
+        results = {"verified": 0, "partial": 0, "hallucinated": 0}
+        for line in response.iter_lines():
+            if line:
+                chunk = json.loads(line)
+                if chunk["type"] == "result":
+                    if chunk["status"] == "verified":
+                        results["verified"] += 1
+                    elif chunk["status"] == "partial":
+                        results["partial"] += 1
+                    else:
+                        results["hallucinated"] += 1
+
+        total = sum(results.values())
+        print(f"{pdf_path}: {total} refs — {results}")
+    ```
+
+## AGAPI Agent [WIP]
 
 ```python
 from agapi.agents import AGAPIAgent
 import os
 
 agent = AGAPIAgent(api_key=os.environ.get("AGAPI_KEY"))
-response = agent.query_sync("Show hallucination detector for Silicon")
+response = agent.query_sync("Verify the references in this text for hallucinations")
 print(response)
 ```
 
-## Reference
+## References
+
+- [atomgptlab](https://github.com/atomgptlab)
+
+
 
-- —
diff --git a/mkdocs.yml b/mkdocs.yml
index 3d9a036..f0d5a80 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -116,6 +116,7 @@ nav:
       - Vacancy Explorer: apps/explore/vacancy.md
       - Surface Explorer: apps/explore/surface.md
       - Interface Explorer: apps/explore/interface.md
+      - Interface Database: apps/explore/interface-db.md
       - 2D Materials: apps/explore/twod.md
       - Polymer Explorer: apps/explore/polymer.md
       - Force Field DB: apps/explore/ff.md
@@ -125,10 +126,17 @@ nav:
       - PDB Explorer: apps/explore/pdb-explorer.md
       - OPTIMADE Explorer: apps/explore/optimade.md
       - Convex Hull: apps/explore/convexhull.md
+      - Literature Explorer: apps/explore/literature.md
+      - OMIM Gene Explorer: apps/explore/omim.md
+      - SDSS SkyServer: apps/explore/sdss.md
+      - Web Browser: apps/explore/webbrowser.md
+      - Unit Converter: apps/explore/unit-converter.md
+      - Tokenizer Playground: apps/explore/tokenizer.md
     - Build:
       - apps/build/index.md
       - Structure Visualizer: apps/build/structure-visualizer.md
       - Heterostructure Builder: apps/build/heterostructure.md
+      - Polymer Chain Builder: apps/build/polymer-builder.md
       - Workflow Builder: apps/build/workflow.md
     - Predict:
       - apps/predict/index.md
@@ -150,6 +158,9 @@ nav:
       - Battery Explorer: apps/apply/battery.md
       - Catalysis: apps/apply/catalysis.md
       - Direct Air Capture: apps/apply/dac.md
+      - HardMat: apps/apply/hardmat.md
+      - MeltMat: apps/apply/meltmat.md
+      - PourbaixMat: apps/apply/pourbaix.md
     - Validate:
       - apps/validate/index.md
       - AI Detector: apps/validate/ai-detector.md