@delta-infra/cli 1.1.19 → 1.1.23

package/skills/delta-protein/references/consensus_mutation.md

@@ -1,61 +1,61 @@
-# Consensus Mutation Analysis (`huada_protein_tools` / `consensus_mutation`)
-
-This endpoint is a real endpoint of the `huada_protein_tools` tool. It can only be
-called via `delta-cli science invoke`; the business response described below lives
-under the CLI top-level `data` — read fields as documented in this file, do not
-recursively search. This file only documents the endpoint schema; it does not
-authorize direct HTTP. Endpoint names are authoritative as returned by
-`delta-cli science endpoints list huada_protein_tools`; use them verbatim — never
-guess, truncate, or alias.
-
-## Overview
-
-Consensus mutation analysis based on an aligned MSA (A3M).
-- Required: `msa_file` (A3M, usually the `download_url` from generate_msa; aligned columns contain `-` placeholders)
-- Optional: `query_id` (target sequence ID in the MSA; defaults to the first/query sequence when unspecified)
-- Output: consensus mutation analysis results, `download_url`
-- Use case: design/filter mutation sites with consensus information across homolog sequences
-
-## Invocation
-
-```text
-delta-cli science invoke --tool huada_protein_tools --endpoint consensus_mutation --data JSON
-```
-
-Required input groups (at least one per group; all groups must be satisfied):
-
-- `msa_file`
-
-Request fields:
-
-| Field | Description | Default |
-|---|---|---|
-| `msa_file` | A3M MSA | - |
-| `query_id` | Target sequence ID in the MSA; defaults to the first (query) sequence when unspecified | - |
-
-## Response
-
-- CLI top-level envelope: a call succeeds only when the exit code is 0 AND `ok` is `true`; the service response lives under `data`.
-- Server-side contract: `status` (success/error/partial), `message`, `tool_type`, `resultjson`, `download_url`; some endpoints also return `total_count`. `resultjson` may be a single object or an array — read only the keys documented in this file, do not recursively search.
-- Binary/file artifacts (such as the PDB/XLSX/FASTA/ZIP files that `download_url` points to) are downloaded and verified with
-  `delta-cli science file download --tool huada_protein_tools --endpoint ... --output <path>`;
-  do not treat file contents as ordinary JSON results.
-
-## Output Projection
-
-> Verification status: derived from ToolSpec/agent templates; pending live calibration
-
-- Projection content: Consensus mutation residues, support level and recommendation grade
-- Presentation form: Text/table
-- Downstream reuse: -
-## Output Template
-
-- Title: **Consensus mutation analysis result**
-- Lead with the conclusion: positions jointly recommended by multiple models/homolog sequences, support level and overall recommendation grade
-
-## Boundaries & Failure Modes
-
-- File-type parameters (`structure_file`/`sequence_file`/`msa_file` etc.) take server-accessible URL/path strings, not local upload paths; a `download_url` or `pdb_url` returned by an upstream endpoint can be backfilled directly as downstream input.
-- Make only the minimal calls needed to complete the task; `--data` carries only the fields declared by this endpoint. Do not invent enum values or branches beyond the required combinations.
-- Do not pass off local tool (RDKit/pymatgen/LAMMPS/self-attached MCP) results as this endpoint's results; do not connect directly to Huada or gateway URLs.
+# Consensus Mutation Analysis (`huada_protein_tools` / `consensus_mutation`)
+
+This endpoint is a real endpoint of the `huada_protein_tools` tool. It can only be
+called via `delta-cli science invoke`; the business response described below lives
+under the CLI top-level `data` — read fields as documented in this file, do not
+recursively search. This file only documents the endpoint schema; it does not
+authorize direct HTTP. Endpoint names are authoritative as returned by
+`delta-cli science endpoints list huada_protein_tools`; use them verbatim — never
+guess, truncate, or alias.
+
+## Overview
+
+Consensus mutation analysis based on an aligned MSA (A3M).
+- Required: `msa_file` (A3M, usually the `download_url` from generate_msa; aligned columns contain `-` placeholders)
+- Optional: `query_id` (target sequence ID in the MSA; defaults to the first/query sequence when unspecified)
+- Output: consensus mutation analysis results, `download_url`
+- Use case: design/filter mutation sites with consensus information across homolog sequences
+
+## Invocation
+
+```text
+delta-cli science invoke --tool huada_protein_tools --endpoint consensus_mutation --data JSON
+```
+
+Required input groups (at least one per group; all groups must be satisfied):
+
+- `msa_file`
+
+Request fields:
+
+| Field | Description | Default |
+|---|---|---|
+| `msa_file` | A3M MSA | - |
+| `query_id` | Target sequence ID in the MSA; defaults to the first (query) sequence when unspecified | - |
+
+## Response
+
+- CLI top-level envelope: a call succeeds only when the exit code is 0 AND `ok` is `true`; the service response lives under `data`.
+- Server-side contract: `status` (success/error/partial), `message`, `tool_type`, `resultjson`, `download_url`; some endpoints also return `total_count`. `resultjson` may be a single object or an array — read only the keys documented in this file, do not recursively search.
+- Binary/file artifacts (such as the PDB/XLSX/FASTA/ZIP files that `download_url` points to) are downloaded and verified with
+  `delta-cli science file download --tool huada_protein_tools --endpoint ... --output <path>`;
+  do not treat file contents as ordinary JSON results.
+
+## Output Projection
+
+> Verification status: derived from ToolSpec/agent templates; pending live calibration
+
+- Projection content: Consensus mutation residues, support level and recommendation grade
+- Presentation form: Text/table
+- Downstream reuse: -
+## Output Template
+
+- Title: **Consensus mutation analysis result**
+- Lead with the conclusion: positions jointly recommended by multiple models/homolog sequences, support level and overall recommendation grade
+
+## Boundaries & Failure Modes
+
+- File-type parameters (`structure_file`/`sequence_file`/`msa_file` etc.) take server-accessible URL/path strings, not local upload paths; a `download_url` or `pdb_url` returned by an upstream endpoint can be backfilled directly as downstream input.
+- Make only the minimal calls needed to complete the task; `--data` carries only the fields declared by this endpoint. Do not invent enum values or branches beyond the required combinations.
+- Do not pass off local tool (RDKit/pymatgen/LAMMPS/self-attached MCP) results as this endpoint's results; do not connect directly to Huada or gateway URLs.
 - On failure, report a short summary of the CLI's raw error; do not blindly retry after remote computation timeouts (the outcome may be unknown because the task may already have happened).

package/skills/delta-protein/references/consurf_predict.md

@@ -1,67 +1,67 @@
-# Residue Conservation Analysis (`huada_protein_tools` / `consurf_predict`)
-
-This endpoint is a real endpoint of the `huada_protein_tools` tool. It can only be
-called via `delta-cli science invoke`; the business response described below lives
-under the CLI top-level `data` — read fields as documented in this file, do not
-recursively search. This file only documents the endpoint schema; it does not
-authorize direct HTTP. Endpoint names are authoritative as returned by
-`delta-cli science endpoints list huada_protein_tools`; use them verbatim — never
-guess, truncate, or alias.
-
-## Overview
-
-Compute protein residue conservation with ConSurf.
-- Required: `structure_file` (.pdb/.cif)
-- Required: `DB` (server-validated required; SWISS-PROT/UNIREF100, default UNIREF100 — but **must be passed explicitly**; omitting it returns a validation error)
-- Optional: `chain` (A)
-- Output: conservation results `resultjson`, `download_url`
-- Use case: identify functionally important residues, conserved regions
-
-## Invocation
-
-```text
-delta-cli science invoke --tool huada_protein_tools --endpoint consurf_predict --data JSON
-```
-
-Required input groups (at least one per group; all groups must be satisfied):
-
-- `structure_file`
-
-Request fields:
-
-| Field | Description | Default |
-|---|---|---|
-| `structure_file` | PDB/CIF | - |
-| `chain` | Protein chain identifier, default A | A |
-| `DB` | Database: SWISS-PROT/UNIREF100. **Server-required** (defaults to UNIREF100 but errors when omitted — must be passed explicitly) | UNIREF100 |
-
-## Response
-
-- CLI top-level envelope: a call succeeds only when the exit code is 0 AND `ok` is `true`; the service response lives under `data`.
-- Server-side contract: `status` (success/error/partial), `message`, `tool_type`, `resultjson`, `download_url`; some endpoints also return `total_count`. `resultjson` may be a single object or an array — read only the keys documented in this file, do not recursively search.
-- Binary/file artifacts (such as the PDB/XLSX/FASTA/ZIP files that `download_url` points to) are downloaded and verified with
-  `delta-cli science file download --tool huada_protein_tools --endpoint ... --output <path>`;
-  do not treat file contents as ordinary JSON results.
-
-## Output Projection
-
-> Verification status: verified by a real `delta-cli` invocation
-
-- Projection content: Conserved residue count and list (pos/seq/conserved_rank/conserved_score); presented grouped by conservation level
-- Presentation form: Residue list; interpretation: lower conserved_score = more conserved, larger conserved_rank = more conserved
-- Downstream reuse: conservation is only a reference annotation for the zero_shot_mutant_candidates recommendation rationale, not a recommendation criterion
-## Output Template
-
-- Title: **Residue conservation analysis result (ConSurf)**
-- Interpretation: larger conserved_rank = more conserved (7/8/9 conserved, 1/2/3 variable); lower conserved_score = more conserved
-- List positions grouped as conserved/variable (pos/residue/rank/score), explaining the functional or engineering significance of conserved/variable regions
-- May provide conservation reference notes for the "Recommendation/rationale" column of zero_shot_mutant_candidates (annotation only, not a recommendation criterion)
-
-## Boundaries & Failure Modes
-
-- `DB` is a server-required field: omitting it returns a validation error (e.g. missing DB); always pass it explicitly, e.g. `--data '{"structure_file":...,"DB":"UNIREF100"}'`.
-- General principle: fields marked as "default" in this package's references and ToolSpecs are fill-in conveniences for the backend agent orchestration layer; they are **NOT omissible when calling the CLI directly**; whatever the server actually validates is authoritative — when validation reports a missing field, supply it per the error and write it back into the reference.
-- File-type parameters (`structure_file`/`sequence_file`/`msa_file` etc.) take server-accessible URL/path strings, not local upload paths; a `download_url` or `pdb_url` returned by an upstream endpoint can be backfilled directly as downstream input.
-- Make only the minimal calls needed to complete the task; `--data` carries only the fields declared by this endpoint. Do not invent enum values or branches beyond the required combinations.
-- Do not pass off local tool (RDKit/pymatgen/LAMMPS/self-attached MCP) results as this endpoint's results; do not connect directly to Huada or gateway URLs.
+# Residue Conservation Analysis (`huada_protein_tools` / `consurf_predict`)
+
+This endpoint is a real endpoint of the `huada_protein_tools` tool. It can only be
+called via `delta-cli science invoke`; the business response described below lives
+under the CLI top-level `data` — read fields as documented in this file, do not
+recursively search. This file only documents the endpoint schema; it does not
+authorize direct HTTP. Endpoint names are authoritative as returned by
+`delta-cli science endpoints list huada_protein_tools`; use them verbatim — never
+guess, truncate, or alias.
+
+## Overview
+
+Compute protein residue conservation with ConSurf.
+- Required: `structure_file` (.pdb/.cif)
+- Required: `DB` (server-validated required; SWISS-PROT/UNIREF100, default UNIREF100 — but **must be passed explicitly**; omitting it returns a validation error)
+- Optional: `chain` (A)
+- Output: conservation results `resultjson`, `download_url`
+- Use case: identify functionally important residues, conserved regions
+
+## Invocation
+
+```text
+delta-cli science invoke --tool huada_protein_tools --endpoint consurf_predict --data JSON
+```
+
+Required input groups (at least one per group; all groups must be satisfied):
+
+- `structure_file`
+
+Request fields:
+
+| Field | Description | Default |
+|---|---|---|
+| `structure_file` | PDB/CIF | - |
+| `chain` | Protein chain identifier, default A | A |
+| `DB` | Database: SWISS-PROT/UNIREF100. **Server-required** (defaults to UNIREF100 but errors when omitted — must be passed explicitly) | UNIREF100 |
+
+## Response
+
+- CLI top-level envelope: a call succeeds only when the exit code is 0 AND `ok` is `true`; the service response lives under `data`.
+- Server-side contract: `status` (success/error/partial), `message`, `tool_type`, `resultjson`, `download_url`; some endpoints also return `total_count`. `resultjson` may be a single object or an array — read only the keys documented in this file, do not recursively search.
+- Binary/file artifacts (such as the PDB/XLSX/FASTA/ZIP files that `download_url` points to) are downloaded and verified with
+  `delta-cli science file download --tool huada_protein_tools --endpoint ... --output <path>`;
+  do not treat file contents as ordinary JSON results.
+
+## Output Projection
+
+> Verification status: verified by a real `delta-cli` invocation
+
+- Projection content: Conserved residue count and list (pos/seq/conserved_rank/conserved_score); presented grouped by conservation level
+- Presentation form: Residue list; interpretation: lower conserved_score = more conserved, larger conserved_rank = more conserved
+- Downstream reuse: conservation is only a reference annotation for the zero_shot_mutant_candidates recommendation rationale, not a recommendation criterion
+## Output Template
+
+- Title: **Residue conservation analysis result (ConSurf)**
+- Interpretation: larger conserved_rank = more conserved (7/8/9 conserved, 1/2/3 variable); lower conserved_score = more conserved
+- List positions grouped as conserved/variable (pos/residue/rank/score), explaining the functional or engineering significance of conserved/variable regions
+- May provide conservation reference notes for the "Recommendation/rationale" column of zero_shot_mutant_candidates (annotation only, not a recommendation criterion)
+
+## Boundaries & Failure Modes
+
+- `DB` is a server-required field: omitting it returns a validation error (e.g. missing DB); always pass it explicitly, e.g. `--data '{"structure_file":...,"DB":"UNIREF100"}'`.
+- General principle: fields marked as "default" in this package's references and ToolSpecs are fill-in conveniences for the backend agent orchestration layer; they are **NOT omissible when calling the CLI directly**; whatever the server actually validates is authoritative — when validation reports a missing field, supply it per the error and write it back into the reference.
+- File-type parameters (`structure_file`/`sequence_file`/`msa_file` etc.) take server-accessible URL/path strings, not local upload paths; a `download_url` or `pdb_url` returned by an upstream endpoint can be backfilled directly as downstream input.
+- Make only the minimal calls needed to complete the task; `--data` carries only the fields declared by this endpoint. Do not invent enum values or branches beyond the required combinations.
+- Do not pass off local tool (RDKit/pymatgen/LAMMPS/self-attached MCP) results as this endpoint's results; do not connect directly to Huada or gateway URLs.
 - On failure, report a short summary of the CLI's raw error; do not blindly retry after remote computation timeouts (the outcome may be unknown because the task may already have happened).

package/skills/delta-protein/references/crop_sequence.md

@@ -1,69 +1,69 @@
-# Protein Sequence Cropping (`huada_protein_tools` / `crop_sequence`)
-
-This endpoint is a real endpoint of the `huada_protein_tools` tool. It can only be
-called via `delta-cli science invoke`; the business response described below lives
-under the CLI top-level `data` — read fields as documented in this file, do not
-recursively search. This file only documents the endpoint schema; it does not
-authorize direct HTTP. Endpoint names are authoritative as returned by
-`delta-cli science endpoints list huada_protein_tools`; use them verbatim — never
-guess, truncate, or alias.
-
-## Overview
-
-Crop subsequences from a protein sequence by given regions and return a merged FASTA
-file.
-- Input: `protein_sequence` / `sequence_file` / `structure_file` (choose one)
-- `protein_sequence`: a single one-letter amino-acid sequence
-- `sequence_file`: FASTA/FA file URL
-- `structure_file`: PDB/CIF file URL (the sequence is extracted from the specified chain)
-- Required: `regions`, a list of crop intervals, each `[start, end]` (1-based, inclusive). For example `[[100, 200], [250, 300]]` crops two independent sequences
-- Optional: `chain`, protein chain identifier, default A
-- Output: `resultjson` contains `cropped_results` (name/start/end/length/sequence per region); `download_url` is the merged FASTA download link
-
-## Invocation
-
-```text
-delta-cli science invoke --tool huada_protein_tools --endpoint crop_sequence --data JSON
-```
-
-Required input groups (at least one per group; all groups must be satisfied):
-
-- `protein_sequence` / `sequence_file` / `structure_file` **and** `regions`
-
-Request fields:
-
-| Field | Description | Default |
-|---|---|---|
-| `protein_sequence` |  | - |
-| `sequence_file` | FASTA/FA | - |
-| `structure_file` | PDB/CIF | - |
-| `chain` | Protein chain identifier, default A | A |
-| `regions` | List of crop intervals, each [start, end] (1-based, inclusive). E.g. [[100, 200], [250, 300]] crops 100-200 and 250-300, each output as an independent sequence | - |
-
-## Response
-
-- CLI top-level envelope: a call succeeds only when the exit code is 0 AND `ok` is `true`; the service response lives under `data`.
-- Server-side contract: `status` (success/error/partial), `message`, `tool_type`, `resultjson`, `download_url`; some endpoints also return `total_count`. `resultjson` may be a single object or an array — read only the keys documented in this file, do not recursively search.
-- Binary/file artifacts (such as the PDB/XLSX/FASTA/ZIP files that `download_url` points to) are downloaded and verified with
-  `delta-cli science file download --tool huada_protein_tools --endpoint ... --output <path>`;
-  do not treat file contents as ordinary JSON results.
-
-## Output Projection
-
-> Verification status: derived from ToolSpec/agent templates; pending live calibration
-
-- Projection content: cropped_results: name/start/end/length/sequence per region + merged FASTA download_url
-- Presentation form: Sequence inline code + FASTA link
-- Downstream reuse: -
-## Output Template
-
-- Title: **Protein sequence cropping result**
-- One entry per region: range (start-end) and cropped sequence (inline code)
-- Add the merged FASTA to the "Result files & downloads" section
-
-## Boundaries & Failure Modes
-
-- File-type parameters (`structure_file`/`sequence_file`/`msa_file` etc.) take server-accessible URL/path strings, not local upload paths; a `download_url` or `pdb_url` returned by an upstream endpoint can be backfilled directly as downstream input.
-- Make only the minimal calls needed to complete the task; `--data` carries only the fields declared by this endpoint. Do not invent enum values or branches beyond the required combinations.
-- Do not pass off local tool (RDKit/pymatgen/LAMMPS/self-attached MCP) results as this endpoint's results; do not connect directly to Huada or gateway URLs.
+# Protein Sequence Cropping (`huada_protein_tools` / `crop_sequence`)
+
+This endpoint is a real endpoint of the `huada_protein_tools` tool. It can only be
+called via `delta-cli science invoke`; the business response described below lives
+under the CLI top-level `data` — read fields as documented in this file, do not
+recursively search. This file only documents the endpoint schema; it does not
+authorize direct HTTP. Endpoint names are authoritative as returned by
+`delta-cli science endpoints list huada_protein_tools`; use them verbatim — never
+guess, truncate, or alias.
+
+## Overview
+
+Crop subsequences from a protein sequence by given regions and return a merged FASTA
+file.
+- Input: `protein_sequence` / `sequence_file` / `structure_file` (choose one)
+- `protein_sequence`: a single one-letter amino-acid sequence
+- `sequence_file`: FASTA/FA file URL
+- `structure_file`: PDB/CIF file URL (the sequence is extracted from the specified chain)
+- Required: `regions`, a list of crop intervals, each `[start, end]` (1-based, inclusive). For example `[[100, 200], [250, 300]]` crops two independent sequences
+- Optional: `chain`, protein chain identifier, default A
+- Output: `resultjson` contains `cropped_results` (name/start/end/length/sequence per region); `download_url` is the merged FASTA download link
+
+## Invocation
+
+```text
+delta-cli science invoke --tool huada_protein_tools --endpoint crop_sequence --data JSON
+```
+
+Required input groups (at least one per group; all groups must be satisfied):
+
+- `protein_sequence` / `sequence_file` / `structure_file` **and** `regions`
+
+Request fields:
+
+| Field | Description | Default |
+|---|---|---|
+| `protein_sequence` |  | - |
+| `sequence_file` | FASTA/FA | - |
+| `structure_file` | PDB/CIF | - |
+| `chain` | Protein chain identifier, default A | A |
+| `regions` | List of crop intervals, each [start, end] (1-based, inclusive). E.g. [[100, 200], [250, 300]] crops 100-200 and 250-300, each output as an independent sequence | - |
+
+## Response
+
+- CLI top-level envelope: a call succeeds only when the exit code is 0 AND `ok` is `true`; the service response lives under `data`.
+- Server-side contract: `status` (success/error/partial), `message`, `tool_type`, `resultjson`, `download_url`; some endpoints also return `total_count`. `resultjson` may be a single object or an array — read only the keys documented in this file, do not recursively search.
+- Binary/file artifacts (such as the PDB/XLSX/FASTA/ZIP files that `download_url` points to) are downloaded and verified with
+  `delta-cli science file download --tool huada_protein_tools --endpoint ... --output <path>`;
+  do not treat file contents as ordinary JSON results.
+
+## Output Projection
+
+> Verification status: derived from ToolSpec/agent templates; pending live calibration
+
+- Projection content: cropped_results: name/start/end/length/sequence per region + merged FASTA download_url
+- Presentation form: Sequence inline code + FASTA link
+- Downstream reuse: -
+## Output Template
+
+- Title: **Protein sequence cropping result**
+- One entry per region: range (start-end) and cropped sequence (inline code)
+- Add the merged FASTA to the "Result files & downloads" section
+
+## Boundaries & Failure Modes
+
+- File-type parameters (`structure_file`/`sequence_file`/`msa_file` etc.) take server-accessible URL/path strings, not local upload paths; a `download_url` or `pdb_url` returned by an upstream endpoint can be backfilled directly as downstream input.
+- Make only the minimal calls needed to complete the task; `--data` carries only the fields declared by this endpoint. Do not invent enum values or branches beyond the required combinations.
+- Do not pass off local tool (RDKit/pymatgen/LAMMPS/self-attached MCP) results as this endpoint's results; do not connect directly to Huada or gateway URLs.
 - On failure, report a short summary of the CLI's raw error; do not blindly retry after remote computation timeouts (the outcome may be unknown because the task may already have happened).

package/skills/delta-protein/references/dock.md

@@ -1,82 +1,82 @@
-# Molecular Docking (`huada_protein_tools` / `dock`)
-
-This endpoint is a real endpoint of the `huada_protein_tools` tool. It can only be
-called via `delta-cli science invoke`; the business response described below lives
-under the CLI top-level `data` — read fields as documented in this file, do not
-recursively search. This file only documents the endpoint schema; it does not
-authorize direct HTTP. Endpoint names are authoritative as returned by
-`delta-cli science endpoints list huada_protein_tools`; use them verbatim — never
-guess, truncate, or alias.
-
-## Overview
-
-Protein-ligand molecular docking with AutoDock Vina.
-- Input: `structure_file` (PDB/CIF) or `protein_sequence` (structure must be predicted first) / `sequence_file` (FASTA) — choose one
-- `ligand_source`: ligand SMILES string or ligand file path (.sdf/.mol2/.txt). Optional; when missing, the backend returns a friendly hint and the request is still forwarded to the backend for handling
-- Optional:
-- `cofactor_mode` (str): "keep" or "remove", default "keep"
-- `cofactors` (list[str]): cofactor/ligand residue names, e.g. ["ATP","MG"], default auto-handled
-- `box_center` (str): manually specified docking box center, format "x,y,z"
-- `box_size` (str): manually specified docking box size, a single number or "w,h,d"
-- `ph` (float): protonation pH, default 7.4
-- `exhaustiveness` (int): Vina search exhaustiveness, default 16
-- `n_poses` (int): number of output poses, default 10
-- `cpu` (int): number of CPU cores, default 8
-- Box behavior: `box_center`/`box_size` can be given alone or together — when both are given they are used directly; when only `box_size` is given, the center is auto-detected by local p2rank (size uses this value, default 20Å); when neither is given, the backend tries the bounding box of the removed cofactor residues / p2rank auto-detected pockets in turn; with p2rank auto-detection each detected pocket is docked separately (one box per pocket, max 10 pockets by score); when p2rank finds no pocket it errors and box parameters must be provided manually
-- Output: `download_url` is the multi-conformer PDB (docked_poses.pdb, merged across pockets, containing all pose MODELs) for visualization; each `resultjson` entry contains {affinity, rmsd_lb, rmsd_ub, pocket, pdb_url}; `pocket` identifies the associated pocket (p2rank's rank/name/score/center; {"rank": N} for a single box); `pdb_url` is provided only on the rank-1 entry, pointing to a single clean best-complex PDB (full receptor + ligand, ligand in chain L), suitable for PLIP interaction analysis
-
-## Invocation
-
-```text
-delta-cli science invoke --tool huada_protein_tools --endpoint dock --data JSON
-```
-
-Required input groups (at least one per group; all groups must be satisfied):
-
-- `protein_sequence` / `sequence_file` / `structure_file` / `ligand_source`
-
-Request fields:
-
-| Field | Description | Default |
-|---|---|---|
-| `protein_sequence` |  | - |
-| `sequence_file` | FASTA/FA | - |
-| `structure_file` | PDB/CIF | - |
-| `ligand_source` | Ligand SMILES string or ligand file path (.sdf/.mol2/.txt); optional, backend returns a hint when missing | - |
-| `cofactor_mode` | Cofactor handling mode, default "keep" | keep |
-| `cofactors` | Cofactor/ligand residue name list, default None | - |
-| `box_center` | Manually specified docking box center, format x,y,z | - |
-| `box_size` | Manually specified docking box size, a single number or w,h,d | - |
-| `ph` | Protonation pH, default 7.4 | 7.4 |
-| `exhaustiveness` | Vina search exhaustiveness, default 16 | 16 |
-| `n_poses` | Number of output poses, default 10 | 10 |
-| `cpu` | Number of CPU cores, default 8 | 8 |
-
-## Response
-
-- CLI top-level envelope: a call succeeds only when the exit code is 0 AND `ok` is `true`; the service response lives under `data`.
-- Server-side contract: `status` (success/error/partial), `message`, `tool_type`, `resultjson`, `download_url`; some endpoints also return `total_count`. `resultjson` may be a single object or an array — read only the keys documented in this file, do not recursively search.
-- Binary/file artifacts (such as the PDB/XLSX/FASTA/ZIP files that `download_url` points to) are downloaded and verified with
-  `delta-cli science file download --tool huada_protein_tools --endpoint ... --output <path>`;
-  do not treat file contents as ordinary JSON results.
-
-## Output Projection
-
-> Verification status: verified by a real `delta-cli` invocation
-
-- Projection content: affinity per pose (binding energy, kcal/mol), rmsd_lb/rmsd_ub, associated pocket; rank-1 carries pdb_url (clean complex); best score read from message or the minimal affinity
-- Presentation form: Pose list text (affinity & RMSD) + multi-conformer PDB download link
-- Downstream reuse: rank-1 pdb_url -> plip_analyze structure_file
-## Output Template
-
-- Title: **Molecular docking result**
-- Lead with the conclusion: best score (best affinity, kcal/mol) and the associated pocket
-- List poses sorted by score (affinity/rmsd_lb/rmsd_ub, mark the pocket when multiple pockets)
-- Add the multi-conformer PDB to the "Result files & downloads" section; give rank-1 pdb_url separately (usable as PLIP input)
-
-## Boundaries & Failure Modes
-
-- File-type parameters (`structure_file`/`sequence_file`/`msa_file` etc.) take server-accessible URL/path strings, not local upload paths; a `download_url` or `pdb_url` returned by an upstream endpoint can be backfilled directly as downstream input.
-- Make only the minimal calls needed to complete the task; `--data` carries only the fields declared by this endpoint. Do not invent enum values or branches beyond the required combinations.
-- Do not pass off local tool (RDKit/pymatgen/LAMMPS/self-attached MCP) results as this endpoint's results; do not connect directly to Huada or gateway URLs.
+# Molecular Docking (`huada_protein_tools` / `dock`)
+
+This endpoint is a real endpoint of the `huada_protein_tools` tool. It can only be
+called via `delta-cli science invoke`; the business response described below lives
+under the CLI top-level `data` — read fields as documented in this file, do not
+recursively search. This file only documents the endpoint schema; it does not
+authorize direct HTTP. Endpoint names are authoritative as returned by
+`delta-cli science endpoints list huada_protein_tools`; use them verbatim — never
+guess, truncate, or alias.
+
+## Overview
+
+Protein-ligand molecular docking with AutoDock Vina.
+- Input: `structure_file` (PDB/CIF) or `protein_sequence` (structure must be predicted first) / `sequence_file` (FASTA) — choose one
+- `ligand_source`: ligand SMILES string or ligand file path (.sdf/.mol2/.txt). Optional; when missing, the backend returns a friendly hint and the request is still forwarded to the backend for handling
+- Optional:
+- `cofactor_mode` (str): "keep" or "remove", default "keep"
+- `cofactors` (list[str]): cofactor/ligand residue names, e.g. ["ATP","MG"], default auto-handled
+- `box_center` (str): manually specified docking box center, format "x,y,z"
+- `box_size` (str): manually specified docking box size, a single number or "w,h,d"
+- `ph` (float): protonation pH, default 7.4
+- `exhaustiveness` (int): Vina search exhaustiveness, default 16
+- `n_poses` (int): number of output poses, default 10
+- `cpu` (int): number of CPU cores, default 8
+- Box behavior: `box_center`/`box_size` can be given alone or together — when both are given they are used directly; when only `box_size` is given, the center is auto-detected by local p2rank (size uses this value, default 20Å); when neither is given, the backend tries the bounding box of the removed cofactor residues / p2rank auto-detected pockets in turn; with p2rank auto-detection each detected pocket is docked separately (one box per pocket, max 10 pockets by score); when p2rank finds no pocket it errors and box parameters must be provided manually
+- Output: `download_url` is the multi-conformer PDB (docked_poses.pdb, merged across pockets, containing all pose MODELs) for visualization; each `resultjson` entry contains {affinity, rmsd_lb, rmsd_ub, pocket, pdb_url}; `pocket` identifies the associated pocket (p2rank's rank/name/score/center; {"rank": N} for a single box); `pdb_url` is provided only on the rank-1 entry, pointing to a single clean best-complex PDB (full receptor + ligand, ligand in chain L), suitable for PLIP interaction analysis
+
+## Invocation
+
+```text
+delta-cli science invoke --tool huada_protein_tools --endpoint dock --data JSON
+```
+
+Required input groups (at least one per group; all groups must be satisfied):
+
+- `protein_sequence` / `sequence_file` / `structure_file` / `ligand_source`
+
+Request fields:
+
+| Field | Description | Default |
+|---|---|---|
+| `protein_sequence` |  | - |
+| `sequence_file` | FASTA/FA | - |
+| `structure_file` | PDB/CIF | - |
+| `ligand_source` | Ligand SMILES string or ligand file path (.sdf/.mol2/.txt); optional, backend returns a hint when missing | - |
+| `cofactor_mode` | Cofactor handling mode, default "keep" | keep |
+| `cofactors` | Cofactor/ligand residue name list, default None | - |
+| `box_center` | Manually specified docking box center, format x,y,z | - |
+| `box_size` | Manually specified docking box size, a single number or w,h,d | - |
+| `ph` | Protonation pH, default 7.4 | 7.4 |
+| `exhaustiveness` | Vina search exhaustiveness, default 16 | 16 |
+| `n_poses` | Number of output poses, default 10 | 10 |
+| `cpu` | Number of CPU cores, default 8 | 8 |
+
+## Response
+
+- CLI top-level envelope: a call succeeds only when the exit code is 0 AND `ok` is `true`; the service response lives under `data`.
+- Server-side contract: `status` (success/error/partial), `message`, `tool_type`, `resultjson`, `download_url`; some endpoints also return `total_count`. `resultjson` may be a single object or an array — read only the keys documented in this file, do not recursively search.
+- Binary/file artifacts (such as the PDB/XLSX/FASTA/ZIP files that `download_url` points to) are downloaded and verified with
+  `delta-cli science file download --tool huada_protein_tools --endpoint ... --output <path>`;
+  do not treat file contents as ordinary JSON results.
+
+## Output Projection
+
+> Verification status: verified by a real `delta-cli` invocation
+
+- Projection content: affinity per pose (binding energy, kcal/mol), rmsd_lb/rmsd_ub, associated pocket; rank-1 carries pdb_url (clean complex); best score read from message or the minimal affinity
+- Presentation form: Pose list text (affinity & RMSD) + multi-conformer PDB download link
+- Downstream reuse: rank-1 pdb_url -> plip_analyze structure_file
+## Output Template
+
+- Title: **Molecular docking result**
+- Lead with the conclusion: best score (best affinity, kcal/mol) and the associated pocket
+- List poses sorted by score (affinity/rmsd_lb/rmsd_ub, mark the pocket when multiple pockets)
+- Add the multi-conformer PDB to the "Result files & downloads" section; give rank-1 pdb_url separately (usable as PLIP input)
+
+## Boundaries & Failure Modes
+
+- File-type parameters (`structure_file`/`sequence_file`/`msa_file` etc.) take server-accessible URL/path strings, not local upload paths; a `download_url` or `pdb_url` returned by an upstream endpoint can be backfilled directly as downstream input.
+- Make only the minimal calls needed to complete the task; `--data` carries only the fields declared by this endpoint. Do not invent enum values or branches beyond the required combinations.
+- Do not pass off local tool (RDKit/pymatgen/LAMMPS/self-attached MCP) results as this endpoint's results; do not connect directly to Huada or gateway URLs.
 - On failure, report a short summary of the CLI's raw error; do not blindly retry after remote computation timeouts (the outcome may be unknown because the task may already have happened).