PerinMu · PerinMu · Aug 4, 2026 · Aug 4, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,24 @@ All notable changes to this project will be documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project intends to use semantic
 versioning after the initial alpha releases.
 
+## [0.2.0] - 2026-08-04
+
+### Added
+
+- Expanded site-specific peptide PTMs and terminal groups, including acylation, methylation,
+  oxidation-state, sulfation, ubiquitin-remnant, nitration, ester, and hydrazide representations.
+- Site-aware aliases for selected Unimod accessions.
+- Layerable JSON custom-modification registries, a JSON Schema, Python registration APIs, and
+  explicit override protection.
+- English project homepage with linked Simplified Chinese documentation.
+- Structural formula tests, registry validation tests, custom CLI examples, and modification-system
+  documentation.
+
+### Changed
+
+- Generalized peptide parsing and conversion APIs to accept a modification registry.
+- `formats` now reports active modifications and accepts repeatable `--mod-config` files.
+
 ## [0.1.0] - 2026-08-04
 
 ### Added

diff --git a/CITATION.cff b/CITATION.cff
@@ -4,7 +4,7 @@ title: "MolTranscode"
 type: software
 authors:
   - family-names: "PerinMu"
-version: 0.1.0
+version: 0.2.0
 date-released: 2026-08-04
 license: MIT
 repository-code: "https://github.com/PerinMu/MolTranscode"

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -7,5 +7,17 @@
    new modification.
 5. Do not map a mass shift or ambiguous name to a structure without an explicit resolution rule.
 
+## Adding modifications
+
+Use a JSON registry first for laboratory- or project-specific chemistry; see
+[`docs/modifications.md`](docs/modifications.md). A modification belongs in the built-in registry
+only when it has a stable controlled-vocabulary or primary-literature reference and a broadly useful
+structural interpretation.
+
+Built-in proposals must document residue/terminus specificity, attachment semantics, formal charge,
+tautomer and stereochemical choices. Include RDKit sanitization plus formula or exact-mass tests.
+Aliases that resemble controlled-vocabulary accessions must be site-aware and traceable to the
+corresponding record. Never silently replace an existing definition.
+
 Bug reports should include the exact input, requested formats, full error, Python version, and output
 of `moltranscode --version`. Never include confidential structures in a public issue.
diff --git a/README.md b/README.md
@@ -1,34 +1,38 @@
 # MolTranscode
 
+[简体中文](README.zh-CN.md)
+
 [![CI](https://github.com/PerinMu/MolTranscode/actions/workflows/ci.yml/badge.svg)](https://github.com/PerinMu/MolTranscode/actions/workflows/ci.yml)
 [![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
-**MolTranscode** 是一个可审计、可批处理的分子表示转码工具。它把原来的“肽序列手工拼接
-SMILES”脚本整理成 Python 包和命令行程序，面向肽/蛋白序列、小分子结构与机器学习特征。
+**MolTranscode** is an auditable, batch-friendly toolkit for transcoding molecular
+representations without hiding chemical ambiguity. It connects peptide and protein sequences,
+small-molecule formats, line notations, descriptors, and fingerprints through one Python API and
+command-line interface.
 
-> Transcode molecular representations without hiding chemical ambiguity.
->
-> 不同表示之间并非都能无损互转。SMILES 描述的是分子图，不保存
-> FASTA 注释、蛋白高级结构或实验条件；任意 SMILES 也无法可靠还原成唯一的肽序列。
+> Molecular representations are not universally lossless. SMILES stores a molecular graph, not a
+> FASTA header, residue numbering, conformational ensemble, pH, or experimental context. An
+> arbitrary SMILES string therefore cannot be claimed to have one uniquely recoverable peptide
+> sequence.
 
-## 功能
+## Highlights
 
-- 输入：肽/蛋白序列、FASTA、HELM（RDKit 支持的肽子集）、SMILES、InChI、SELFIES、
-  MOL、SDF、CSV、TSV、TXT、JSONL
-- 输出：canonical/isomeric SMILES、InChI、InChIKey、SELFIES、MOL、SDF、PDB、
-  FASTA/序列（仅保留单体信息的来源）
-- 肽修饰：N 端乙酰化、C 端酰胺化、残基骨架 N-甲基化，以及常见的磷酸化、氧化、
-  Lys 甲基化/二甲基化/三甲基化、Lys 乙酰化、Cys 甲基化和 carbamidomethyl
-- 指纹：Morgan/ECFP-like、RDKit path、MACCS、Atom Pair、Topological Torsion，另有蛋白
-  序列 k-mer 哈希指纹
-- 描述符：分子式、精确质量、MolLogP、TPSA、HBD/HBA、可旋转键、重原子数、电荷
-- 可选在线名称解析：通过 PubChem PUG-REST 将常用名/CAS 等解析为结构
-- 批处理输出逐条记录 `status` 与 `error`，不会因单条坏数据丢失整批结果
+- Inputs: peptide/protein sequences, FASTA, peptide HELM, SMILES, InChI, SELFIES, MOL, SDF, PDB,
+  CSV, TSV, TXT, and JSONL
+- Outputs: canonical/isomeric SMILES, InChI, InChIKey, SELFIES, MOL, SDF, PDB, and metadata-assisted
+  FASTA/sequence/HELM
+- Linear L/D peptide construction with explicit termini, backbone N-methylation, curated PTMs, and
+  site-aware Unimod aliases
+- Layerable JSON registries and a Python API for custom side-chain and terminal structures
+- Morgan, RDKit path, MACCS, Atom Pair, Topological Torsion, and sequence k-mer fingerprints
+- Formula, exact mass, MolLogP, TPSA, HBD/HBA, rotatable-bond, heavy-atom, and charge descriptors
+- Optional PubChem PUG-REST name resolution, kept separate from deterministic local conversion
+- Per-record `status` and `error` fields for resilient batch processing
 
-## 安装
+## Installation
 
-推荐使用 Python 3.10–3.13 的独立环境：
+MolTranscode supports Python 3.10 and newer.
 
 ```bash
 git clone https://github.com/PerinMu/MolTranscode.git
@@ -39,95 +43,199 @@ python -m pip install -U pip
 python -m pip install -e .
 ```
 
-开发环境：
+For development:
 
 ```bash
 python -m pip install -e '.[dev]'
 pytest
 ruff check .
 ```
 
-## 快速开始
+## Quick start
 
 ```bash
-# 标准肽序列；小写字母表示对应 D-氨基酸
+# Standard and modified peptides; lowercase residues are D amino acids
 moltranscode convert ACDY --from peptide --to smiles
-moltranscode convert Ac-AK[Dimethyl]S[Phospho]M[Oxidation]-NH2 --from peptide --to smiles
+moltranscode convert 'Ac-AK[Dimethyl]S[Phospho]M[Oxidation]-NH2' \
+  --from peptide --to smiles
+
+# Site-aware controlled-vocabulary aliases
+moltranscode convert 'AS[UNIMOD:21]M[UNIMOD:35]K[UNIMOD:121]' \
+  --from peptide --to inchikey
 
-# 小分子格式转换
+# Small-molecule representations
 moltranscode convert 'CC(=O)Oc1ccccc1C(=O)O' --from smiles --to inchi
 moltranscode convert 'InChI=1S/CH4/h1H4' --from inchi --to canonical-smiles
 moltranscode convert '[C][C][O]' --from selfies --to smiles
 
-# 指纹与描述符
+# Fingerprints and descriptors
 moltranscode fingerprint 'CCO' --from smiles --kind morgan --format hex
 moltranscode fingerprint MKWVTFISLL --from sequence --kind kmer --bits 512 --k 3
-moltranscode describe 'CCO' --from smiles
+moltranscode describe 'K[Succinyl]' --from peptide
 
-# FASTA/CSV/SDF 批处理
-moltranscode convert proteins.fasta --file --from fasta --to smiles --output out.csv
-moltranscode convert compounds.csv --file --column structure --from smiles --to inchikey --output out.csv
-moltranscode convert compounds.sdf --file --from sdf --to canonical-smiles --output out.jsonl
+# Inspect the active format and modification registry
+moltranscode formats
+moltranscode formats --json
+```
 
-# 在线名称解析（需要网络；结果来自数据库，不是名称语法的本地推导）
-moltranscode resolve-name aspirin --to smiles
+Automatic input detection is deliberately conservative. For example, `CC` can mean ethane SMILES
+or a two-cysteine peptide, so MolTranscode asks for an explicit `--from` value.
+
+## Peptide notation and built-in modifications
+
+MolTranscode accepts a documented, structure-resolving **ProForma-inspired subset**. It supports
+controlled-vocabulary names and selected accessions, but does not claim complete ProForma 2.0
+compliance.
+
+### Termini and backbone
+
+| Notation | Structure represented |
+|---|---|
+| `[Acetyl]-PEPTIDE` or `Ac-PEPTIDE` | N-terminal acetylation |
+| `[Formyl]-PEPTIDE` | N-terminal formylation |
+| `[Myristoyl]-PEPTIDE` | N-terminal myristoylation |
+| `[Palmitoyl]-PEPTIDE` | N-terminal palmitoylation |
+| `PEPTIDE-[Amide]` or `PEPTIDE-NH2` | C-terminal amidation |
+| `PEPTIDE-[MethylEster]` | C-terminal methyl ester |
+| `PEPTIDE-[EthylEster]` | C-terminal ethyl ester |
+| `PEPTIDE-[Hydrazide]` | C-terminal hydrazide |
+| `A[NMe]` | Backbone N-methylation; unavailable on Pro |
+
+### Side chains
+
+| Sites | Built-in modification names |
+|---|---|
+| S, T, Y | `Phospho`, `Sulfo`, `Acetyl` |
+| S, T | `Methyl` |
+| M | `Oxidation`, `Dioxidation` |
+| C | `Oxidation`, `SulfinicAcid`, `SulfonicAcid`, `Persulfide`, `Methyl`, `Carbamidomethyl` |
+| N, Q | `Deamidated` |
+| R | `Citrullination` |
+| K | `Methyl`, `Dimethyl`, `Trimethyl`, `Acetyl`, `Succinyl`, `Malonyl`, `Crotonyl`, `GlyGly`, `Carbamyl` |
+| Y | `Nitro` |
+
+Selected site-aware aliases include `UNIMOD:1`, `UNIMOD:4`, `UNIMOD:7`, `UNIMOD:21`,
+`UNIMOD:34`, `UNIMOD:35`, `UNIMOD:36`, `UNIMOD:37`, `UNIMOD:40`, `UNIMOD:64`,
+`UNIMOD:121`, `UNIMOD:747`, and `UNIMOD:1363`. The same accession can resolve differently by
+site: `R[UNIMOD:7]` is represented as citrulline, while `N[UNIMOD:7]` and `Q[UNIMOD:7]` are
+represented as deamidated residues.
+
+## Custom modification channel
+
+Custom registries extend the structure library without editing MolTranscode source code. They are
+JSON files whose values are **attachment-aware SMILES fragments**, not mass deltas.
+
+```json
+{
+  "schema_version": 1,
+  "override": false,
+  "side_chain_modifications": [
+    {
+      "name": "AzidoLys",
+      "residue": "K",
+      "side_chain_smiles": "CCCCN=[N+]=[N-]",
+      "aliases": ["AzK"]
+    }
+  ],
+  "n_terminal_modifications": [
+    {
+      "name": "Propionyl",
+      "prefix_smiles": "CCC(=O)",
+      "aliases": ["Prop"]
+    }
+  ],
+  "c_terminal_modifications": [
+    {
+      "name": "MethylAmide",
+      "terminus_smiles": "C(=O)NC",
+      "aliases": ["NHMe"]
+    }
+  ]
+}
+```
 
-moltranscode formats
+Use one registry, or layer several in command-line order:
+
+```bash
+moltranscode convert 'Prop-AK[AzK]-NHMe' --from peptide --to smiles \
+  --mod-config examples/custom_modifications.json
+
+moltranscode formats --json --mod-config lab-mods.json --mod-config project-mods.json
 ```
 
-`--from auto` 仅在无歧义时猜测。像 `CC` 既可能是乙烷 SMILES，也可能是两个半胱氨酸，
-工具会要求显式指定 `--from smiles` 或 `--from peptide`。
+Built-in definitions cannot be replaced silently. A registry must set `"override": true` to replace
+an existing site/name pair. Modified D-isoleucine or D-threonine definitions must provide
+`d_side_chain_smiles` so the second stereocenter is explicit. Every final molecule is sanitized by
+RDKit; registry provenance should be archived with generated data.
 
-## 肽修饰语法
+See [Modification system](docs/modifications.md) for the schema, attachment semantics, safety rules,
+and Python registration API.
 
-本项目接受一个明确记录在案的 **ProForma-inspired 子集**，并不声称完整实现 ProForma 2.0：
+## Batch conversion
 
-| 写法 | 含义 | 适用位置 |
-|---|---|---|
-| `Ac-PEPTIDE` 或 `[Acetyl]-PEPTIDE` | N 端乙酰化 | N 端 |
-| `PEPTIDE-NH2` 或 `PEPTIDE-[Amide]` | C 端酰胺化 | C 端 |
-| `A[NMe]` | 肽键氮甲基化 | 除 Pro 外的任意残基 |
-| `S[Phospho]`、`T[Phospho]`、`Y[Phospho]` | 磷酸化 | S/T/Y |
-| `M[Oxidation]` | 甲硫氨酸亚砜 | M |
-| `K[Methyl]`、`K[Dimethyl]`、`K[Trimethyl]` | Lys 侧链甲基化 | K |
-| `K[Acetyl]` | Lys 侧链乙酰化 | K |
-| `C[Methyl]` | Cys S-甲基化 | C |
-| `C[Carbamidomethyl]` | Cys 烷基化 | C |
+```bash
+moltranscode convert proteins.fasta --file --from fasta --to smiles --output out.csv
+moltranscode convert compounds.csv --file --column structure \
+  --from smiles --to inchikey --output out.csv
+moltranscode convert examples/modified_peptides.csv --file --column sequence \
+  --from peptide --to smiles --output peptides.jsonl
+```
 
-歧义修饰（例如未指定定位的质量偏移）、交联、糖链、二硫键、环肽和任意非天然单体目前会
-明确报错。此策略避免生成“语法有效但化学含义错误”的结构。完整复杂大分子表示建议走 HELM
-及其单体库，详见 [科学依据与边界](docs/scientific-basis.md)。
+CSV/TSV/JSONL input columns are preserved during ingestion. Result tables contain `id`, `input`,
+`input_format`, `output_format`, `result`, `status`, and `error`. One invalid record does not discard
+the rest of the batch unless `--fail-fast` is used.
 
 ## Python API
 
 ```python
-from moltranscode import convert, fingerprint, describe
+from moltranscode import convert, describe, fingerprint, load_modification_registry
 
-smiles = convert("Ac-AK[Dimethyl]S[Phospho]-NH2", "peptide", "smiles")
+registry = load_modification_registry("examples/custom_modifications.json")
+
+smiles = convert(
+    "Prop-AK[AzK]-NHMe",
+    "peptide",
+    "smiles",
+    modification_registry=registry,
+)
 fp = fingerprint("CCO", "smiles", kind="morgan", n_bits=2048)
-props = describe("CCO", "smiles")
+properties = describe("K[Succinyl]", "peptide")
 ```
 
-## 项目结构
+Advanced users can construct a `ModificationRegistry` directly and call `register_side_chain()`,
+`register_n_terminus()`, or `register_c_terminus()`.
 
-```text
-src/moltranscode/  # 转换、肽构建、I/O、CLI、PubChem 客户端
-tests/              # 单元测试与 CLI 测试
-examples/           # FASTA、CSV 和修饰肽示例
-docs/               # 科学依据、限制和路线图
-```
+## Scientific and reproducibility boundaries
+
+- Output depends on the RDKit version and MolTranscode parameters; record both with published data.
+- Neutral termini and neutral phosphate/sulfate acid forms are representation policies, not claims
+  about the dominant microspecies at a particular pH.
+- `M[Oxidation]` does not assign sulfur stereochemistry, and `K[Crotonyl]` does not infer alkene E/Z
+  geometry.
+- Mass-only deltas, ambiguous localizations, glycans, cross-links, disulfides, and cyclic peptides
+  are rejected until a unique molecular graph can be constructed.
+- Fingerprints are lossy features, not molecular identity keys. Prefer Standard InChI/InChIKey for
+  identity exchange.
+- `resolve-name` queries PubChem; synonyms can be ambiguous and should be checked against the
+  returned structure.
+
+Read [Scientific basis](docs/scientific-basis.md) and the [Roadmap](docs/roadmap.md) before using the
+tool in a publication workflow.
 
-## 可复现性与安全性
+## Project layout
 
-- 输出由 RDKit 版本决定；论文或数据发布时请同时记录 `moltranscode --version` 与参数。
-- `resolve-name` 会访问 PubChem，名称可能有同义词歧义；关键研究应核对 InChIKey/结构图。
-- 指纹是检索/建模特征，不是分子身份标识；身份交换优先使用 Standard InChI/InChIKey。
-- 本工具不替代化学家审查，也不用于直接给出合成、剂量或安全性结论。
+```text
+src/moltranscode/      conversion, peptide, registry, I/O, and CLI modules
+tests/                 chemistry, registry, batch, and CLI regression tests
+examples/              FASTA, SMI, modified peptide, and custom-registry examples
+docs/                  scientific conventions, modification schema, and roadmap
+```
 
-## 进一步开发
+## Contributing
 
-见 [路线图](docs/roadmap.md)。优先方向包括完整 ProForma 2.0 解析、OpenHELM 单体库、
-环肽/二硫键/交联、核酸、反应 SMILES、3D 构象和大规模流式处理。
+New built-in modifications need an explicit attachment structure, site specificity, stereochemical
+policy, focused formula/structure tests, and a primary or controlled-vocabulary reference. See
+[CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## License