release: v0.2.0

.claude/agents/mpk-documenter.md

@@ -27,7 +27,9 @@ You **maintain** molpack's documentation. You do **NOT** invent API behavior —
 | Python docs | `docs/python/` (the site's "Python" nav section) | Python users |
 | CONTRIBUTING | `CONTRIBUTING.md` | Contributors |
 | README | `README.md` (CLI keyword table, format table, quick-start) | Discovery |
-| Changelog | `CHANGELOG.md` | Users tracking releases |
+
+Release history lives in git tags / GitHub Releases — no hand-written
+`CHANGELOG.md`.
 
 **Sync triggers.** When one of these changes, the listed doc must change too:
 
@@ -38,7 +40,6 @@ You **maintain** molpack's documentation. You do **NOT** invent API behavior —
 | New file format | README format table; `docs/getting_started.md` |
 | Public type added / renamed | rustdoc on the type; Python docs if mirrored |
 | Feature flag added | `Cargo.toml` comment; README install section; CONTRIBUTING test commands |
-| User-visible bug fix | `CHANGELOG.md` |
 
 **Rustdoc style.** Every public item gets a one-line summary plus, for non-trivial items, an example. Examples must compile (`cargo test --doc`). Cross-link via `` [`Item`] `` syntax, never bare names. Use `# Examples`, `# Errors`, `# Panics` sections per Rust API guidelines.
 

.claude/skills/mpk-docs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mpk-docs
-description: Audit or update docs — rustdoc, docs/ (incl. docs/python/), README, CONTRIBUTING, CHANGELOG. Writes docs when asked.
+description: Audit or update docs — rustdoc, docs/ (incl. docs/python/), README, CONTRIBUTING. Writes docs when asked.
 argument-hint: "<git ref, path, or 'update: <topic>'>"
 user-invocable: true
 ---

.claude/skills/mpk-fix/SKILL.md

@@ -16,7 +16,7 @@ Read CLAUDE.md for molpack conventions.
 3. **Diagnose** in place — read the suspect code path. Do not modify code yet.
 4. **Smallest fix.** Edit only what is necessary to flip the test GREEN. Resist the urge to refactor adjacent code, rename variables, or "clean up" while you're there — open a separate `/mpk-refactor` if cleanup is warranted.
 5. **Run impacted tier.** If the fix touches a hot-path file, run the relevant criterion bench. If it touches `restraint.rs`, `objective.rs`, `packer.rs`, `gencan/`, `initial.rs`, `relaxer.rs`, or `movebad.rs`, run `examples_batch`.
-6. **Changelog.** Update `CHANGELOG.md` if the bug was user-visible.
+6. **History.** No `CHANGELOG.md` — release notes come from git tags / GitHub Releases.
 
 ## Output
 

.github/workflows/bench.yml

@@ -20,7 +20,7 @@ on:
 
 # Pin sibling molrs to the same version as Cargo.toml / python/pyproject.toml.
 env:
-  MOLRS_GIT_REF: v0.9.3
+  MOLRS_GIT_REF: v0.12.0
 
 jobs:
   bench:

.github/workflows/ci.yml

@@ -10,7 +10,7 @@ on:
 # Pin sibling molrs to the same version as Cargo.toml / python/pyproject.toml [tool.tox].
 # Bump together when raising molcrafts-molrs / molcrafts-molpy.
 env:
-  MOLRS_GIT_REF: v0.9.3
+  MOLRS_GIT_REF: v0.12.0
 
 # Lint: same as prek commit-stage hooks in .pre-commit-config.yaml.
 # Tests: same commands as prek pre-push hooks (no scripts/).
@@ -71,7 +71,7 @@ jobs:
       - name: Cache test data
         uses: actions/cache@v5
         with:
-          path: molrs/molrs-core/target/tests-data
+          path: molrs/tests-data
           key: ${{ runner.os }}-test-data-${{ hashFiles('molrs/scripts/fetch-test-data.sh') }}
       - name: Fetch test data
         run: bash scripts/fetch-test-data.sh

.github/workflows/publish-crate.yml

@@ -11,7 +11,7 @@ permissions:
 
 # Keep in lockstep with ci.yml / Cargo.toml molrs pin.
 env:
-  MOLRS_GIT_REF: v0.9.3
+  MOLRS_GIT_REF: v0.12.0
 
 jobs:
   ci:

.github/workflows/publish-pypi.yml

@@ -12,7 +12,7 @@ permissions:
 
 # Keep in lockstep with ci.yml / Cargo.toml molrs pin.
 env:
-  MOLRS_GIT_REF: v0.9.3
+  MOLRS_GIT_REF: v0.12.0
 
 # Build matrix produces one wheel per OS per supported Python (3.12, 3.13),
 # matching `requires-python = ">=3.12"` in pyproject.toml. Linux + macOS only;

CONTRIBUTING.md

@@ -22,10 +22,11 @@ workspace/
 The root `Cargo.toml` uses a path dependency on `../molrs/molrs`. With the
 sibling layout above everything resolves automatically.
 
-**Version pins:** path molrs / PyPI `molcrafts-molrs` / `molcrafts-molpy` are
-fixed at **0.9.3** (see `Cargo.toml`, `python/pyproject.toml` `[tool.tox]`, and
-`MOLRS_GIT_REF` in `.github/workflows/ci.yml`). Keep the sibling molrs clone
-on that version line (`git checkout v0.9.3` or the matching release branch).
+**Version pins:** path molrs / PyPI `molcrafts-molrs` / `molcrafts-molpy` track
+the **0.12.*** minor line (see `Cargo.toml`, `python/pyproject.toml` `[tool.tox]`,
+and `MOLRS_GIT_REF` in `.github/workflows/ci.yml`). Patch may differ; only
+major.minor must match. Keep the sibling molrs clone on that minor line
+(`git checkout v0.12.x` or the matching release branch).
 
 **First-time setup:**
 

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "molcrafts-molpack"
-version = "0.1.2"
+version = "0.2.0"
 edition = "2024"
 rust-version = "1.91"
 authors = ["MolCrafts"]
@@ -28,7 +28,7 @@ bench = false
 # Library-required. The merged `molcrafts-molrs` crate exposes its former member
 # crates as feature-gated modules: `core` is always on (re-exported at the crate
 # root), while `io` and `ff` are opt-in via the molpack features below.
-molrs = { path = "../molrs/molrs", version = "0.9.3", package = "molcrafts-molrs", default-features = false }
+molrs = { path = "../molrs/molrs", version = "0.12.0", package = "molcrafts-molrs", default-features = false }
 rand = "0.10"
 ndarray = "0.17"
 log = "0.4"

README.md

@@ -89,7 +89,7 @@ let report = Molpack::new().pack_with_report(&[target], 200)?;
 import molrs
 from molpack import InsideBoxRestraint, Molpack, Target
 
-frame = molrs.read_pdb("water.pdb")
+frame = molrs.io.read_pdb("water.pdb")
 
 water = (
     Target(frame, count=100)

docs/getting_started.md

@@ -20,7 +20,7 @@ type plus PDB/XYZ I/O.
     ```python
     import molrs
 
-    frame = molrs.read_pdb("water.pdb")
+    frame = molrs.io.read_pdb("water.pdb")
     ```
 
 === "In-memory (no file)"
@@ -37,7 +37,8 @@ type plus PDB/XYZ I/O.
                 "z": np.zeros(3),
                 "element": ["O", "H", "H"],
             }
-        }
+        },
+        "meta": {},
     })
     ```
 
@@ -90,8 +91,8 @@ For a frame-only return, use `Molpack().pack([water], max_loops=200)`.
 ```python
 import molrs
 
-molrs.write_pdb(packed, "water_box.pdb")
-# or: molrs.write_xyz(packed, "water_box.xyz")
+molrs.io.write_pdb("water_box.pdb", packed)
+# or: molrs.io.write_xyz("water_box.xyz", packed)
 ```
 
 ## Where next

docs/install.md

@@ -37,7 +37,7 @@ Optional features (crate defaults to none enabled):
 
 ```toml
 # Cargo.toml — common combinations
-molcrafts-molpack = { version = "0.1", features = ["io", "rayon"] }
+molcrafts-molpack = { version = "0.2", features = ["io", "rayon"] }
 ```
 
 ## Python binding

docs/python/api-reference.md

@@ -334,7 +334,7 @@ Raises `ImportError` if `molcrafts-molpy` is not installed.
 ### `load_script(path, *, read_frame=None) -> ScriptJob`
 
 Parse and lower a Packmol-compatible `.inp` script. Template files are
-read on the Python side (defaulting to `molrs.read_pdb` / `read_xyz` by
+read on the Python side (defaulting to `molrs.io.read_pdb` / `read_xyz` by
 extension), so the wheel stays free of `molrs-io`. Pass `read_frame`
 — a callable `(path, filetype) -> molrs.Frame` — to plug in another
 loader (mdtraj, ASE, …).

docs/python/examples.md

@@ -20,7 +20,7 @@ pip install molcrafts-molpack
 ```
 
 `pack_water_cube.py` builds its frame in memory with `molrs.Frame.from_dict`
-(no PDB file); the others load PDB files via `molrs.read_pdb`.
+(no PDB file); the others load PDB files via `molrs.io.read_pdb`.
 
 ## Running
 
@@ -41,8 +41,8 @@ The `pack_mixture.py` example reproduces Packmol's classic `mixture.inp`:
 import molrs
 from molpack import InsideBoxRestraint, Molpack, Target
 
-water_frame = molrs.read_pdb("water.pdb")
-urea_frame  = molrs.read_pdb("urea.pdb")
+water_frame = molrs.io.read_pdb("water.pdb")
+urea_frame  = molrs.io.read_pdb("urea.pdb")
 
 box = InsideBoxRestraint([0, 0, 0], [40, 40, 40])
 
@@ -69,7 +69,8 @@ frame = molrs.Frame.from_dict({
             "z": np.zeros(3),
             "element": ["O", "H", "H"],
         }
-    }
+    },
+    "meta": {},
 })
 
 water = Target(frame, count=100).with_name("water").with_restraint(

docs/python/getting-started.md

@@ -4,13 +4,13 @@ A minimal end-to-end pack: 100 water molecules inside a 40 Å cube.
 
 ## 1. Load a molecule
 
-Use `molrs.read_pdb` to load a template PDB file — the returned
+Use `molrs.io.read_pdb` to load a template PDB file — the returned
 `Frame` can be passed directly to `Target`:
 
 ```python
 import molrs
 
-frame = molrs.read_pdb("water.pdb")
+frame = molrs.io.read_pdb("water.pdb")
 ```
 
 No PDB file? Build a `molrs.Frame` from arrays with `Frame.from_dict`:
@@ -27,7 +27,8 @@ frame = molrs.Frame.from_dict({
             "z": np.zeros(3),
             "element": ["O", "H", "H"],
         }
-    }
+    },
+    "meta": {},
 })
 ```
 
@@ -96,7 +97,7 @@ output. Hand the returned frame to a writer:
 ```python
 import molrs
 
-molrs.write_xyz("packed.xyz", frame)
+molrs.io.write_xyz("packed.xyz", frame)
 ```
 
 Or use `pack_with_report()` and write `result.frame` if you also need
@@ -108,7 +109,7 @@ the diagnostic fields.
 import molrs
 from molpack import InsideBoxRestraint, Molpack, Target
 
-frame = molrs.read_pdb("water.pdb")
+frame = molrs.io.read_pdb("water.pdb")
 
 water = (
     Target(frame, count=100)

docs/python/guide/packer.md

@@ -130,7 +130,7 @@ if not result.converged:
 ```
 
 `PackResult.frame` is the same Frame returned by `pack()`. Pass it to a
-writer of your choice (e.g. `molrs.write_pdb`). molpack does **not**
+writer of your choice (e.g. `molrs.io.write_pdb`). molpack does **not**
 provide writers.
 
 ## Reproducibility

docs/python/guide/targets.md

@@ -18,9 +18,9 @@ target = Target(frame, count)
 
   | Source | Element column |
   |--------|---------------|
-  | `molrs.read_pdb(path)` | `"symbol"` |
-  | `molrs.read_xyz(path)` | `"element"` |
-  | `molrs.Frame.from_dict({"blocks": {"atoms": {...}}})` | `"element"` |
+  | `molrs.io.read_pdb(path)` | `"symbol"` |
+  | `molrs.io.read_xyz(path)` | `"element"` |
+  | `molrs.Frame.from_dict({"blocks": {"atoms": {...}}, "meta": {}})` | `"element"` |
   | `molpy.Frame` | `"element"` |
 
 - `count` — number of copies to produce.
@@ -45,7 +45,8 @@ frame = molrs.Frame.from_dict({
             "z": np.zeros(3),
             "element": ["O", "H", "H"],
         }
-    }
+    },
+    "meta": {},
 })
 water = Target(frame, count=100).with_name("water")
 ```

docs/python/index.md

@@ -13,7 +13,7 @@ reference output.
 import molrs
 from molpack import InsideBoxRestraint, Molpack, Target
 
-frame = molrs.read_pdb("water.pdb")
+frame = molrs.io.read_pdb("water.pdb")
 
 water = (
     Target(frame, count=100)