htpolynet 2.3.1__tar.gz → 2.4.0__tar.gz

htpolynet-2.4.0/.claude/skills/htpolynet/SKILL.md

@@ -0,0 +1 @@
+../../../src/htpolynet/resources/claude/SKILL.md

{htpolynet-2.3.1 → htpolynet-2.4.0}/.github/workflows/docker.yml

@@ -31,6 +31,8 @@ jobs:
         context: .
         file: docker/Dockerfile
         push: true
+        build-args: |
+          HTPOLYNET_COMMIT=${{ github.sha }}
         tags: |
           ghcr.io/cameronabrams/htpolynet:latest
           ghcr.io/cameronabrams/htpolynet:${{ github.sha }}

{htpolynet-2.3.1 → htpolynet-2.4.0}/CHANGELOG.md

@@ -7,6 +7,60 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.4.0] - 2026-08-25
+
+### Added
+
+- **`htpolynet setup-claude` installs the bundled Claude Code skill**, so it
+  reaches users who `pip install` or `conda install` htpolynet rather than
+  only those working inside a clone.  The skill previously lived at
+  `.claude/skills/htpolynet/`, which the tool finds only when the working
+  directory is the repository -- that is contributors, and not most users.
+  It now ships as package data and is copied to
+  `~/.claude/skills/htpolynet/SKILL.md` on request; `--skills-dir
+  ./.claude/skills` scopes it to one project instead, and `--force`
+  overwrites an existing copy after an upgrade.
+
+  Nothing happens at install time: installing the package never writes to
+  `~/.claude/`.  The repository's `.claude/skills/htpolynet/SKILL.md` is now
+  a symbolic link to the packaged file, so a clone and an install get the
+  same skill and the two cannot drift apart.
+
+  The skill itself was rewritten to stand alone.  It used to be a router --
+  its first instruction was to read
+  `docs/source/user-guide/building-a-system.rst`, a path that does not exist
+  for an installed user -- so it now carries the procedure inline and cites
+  Read the Docs once as the full reference.
+
+### Fixed
+
+- **The container image now reports the commit it was built from.**  A
+  published image had no way to say what code it contained: there is no git
+  in the image and no `.git` beside the installed package, so
+  `htpolynet info` fell back to the installed version -- which is right for
+  pip and conda and *misleading for the container*, because the weekly
+  scheduled rebuild builds from `main` HEAD and reports whatever
+  `pyproject.toml` last said.  An image built four commits past a release
+  claimed to be that release, and `:latest` is the default thing people
+  pull.  A user could pull `:latest`, trust the version string, and record
+  the wrong version in a methods section.
+
+  The build now passes the commit as a `HTPOLYNET_COMMIT` build argument,
+  the image carries it in its environment, and `htpolynet info` reports it
+  in preference to the version fallback.  A real git checkout still wins
+  over both, since it reflects the working tree including uncommitted
+  changes.  The container-usage guide explains why `:latest` moves and how
+  to pull by digest or per-commit tag when provenance has to be stateable
+  later.
+
+- The container-usage guide now distinguishes two habits that are easy to
+  conflate: **pulling once** gives a campaign a constant tool chain, while
+  **recording the digest** is what lets you state afterwards what that tool
+  chain was.  The image pins more than the htpolynet code -- Gromacs and
+  AmberTools come unpinned from conda-forge at build time, so two images
+  built days apart can carry different versions of either while running
+  identical htpolynet code.
+
 ## [2.3.1] - 2026-08-25
 
 ### Fixed

{htpolynet-2.3.1 → htpolynet-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: htpolynet
-Version: 2.3.1
+Version: 2.4.0
 Summary: Automated MD System Builder for Amorphous Network Polymers
 Project-URL: Source, https://github.com/cameronabrams/htpolynet
 Project-URL: Documentation, https://htpolynet.readthedocs.io/

{htpolynet-2.3.1 → htpolynet-2.4.0}/ROADMAP.md

@@ -28,35 +28,33 @@ Rough ordering within each section is by value, not by effort.
   the container" is not reproducible. Per-commit tags already exist;
   what's missing is documenting that users should pin one.
 
-- **The container cannot report which commit built it, and its version
-  string is actively misleading between releases.** `htpolynet info` used to
-  print `git commit: unknown` inside the image, because `_get_git_commit()`
-  runs `git rev-parse` against the installed package directory and no
-  installed copy has a `.git` beside it. That now falls back to the
-  installed distribution version, which is right for a pip or conda install
-  and *precisely wrong for the container*: the scheduled rebuild builds from
-  `main` HEAD, which can be many commits past the last tag, so the image
-  reports its `pyproject.toml` version honestly while running code that is
-  not that version.
-
-  This is live, not hypothetical. The 2026-08-24 03:54 scheduled build moved
-  `:latest` to an image built from `948c301` -- four commits past `v2.3.0`
-  -- and that image reports `installed version 2.3.0`. `:latest` is the
-  default thing a user pulls and the weekly cron is what keeps moving it, so
-  the wrong answer is the common case, and it is wrong silently. A user
-  could pull `:latest`, trust the version string, and write "htpolynet
-  2.3.0" in a methods section while having run untagged `main`.
-
-  The fix is to bake the real commit in at image build time -- the build
-  context has `.git`, so `docker.yml` or the Dockerfile can capture
-  `git rev-parse HEAD` and write it where the package can read it. That
-  touches the Dockerfile and the release story together, which is why it was
-  kept out of the bugfix that added the version fallback. It belongs with
-  the build-manifest entry below: both answer "what produced this build",
-  and a manifest that recorded an unreliable version string would launder
-  the problem rather than solve it. Raised by the calibration study, which
-  has correct provenance only because it pins the image by full sha
-  externally -- which remains the right practice either way.
+- **The image's Gromacs and AmberTools are unpinned, so two images with
+  identical htpolynet code can compute different numbers.** `docker/Dockerfile`
+  installs `ambertools`, `gromacs`, `parmed` and `rdkit` from conda-forge with
+  no version constraints, and the weekly rebuild exists precisely to pick up
+  whatever is newest. So the commit stamp now tells you which htpolynet
+  produced a build, and still does not tell you which force-field tool chain
+  did. Observed live: the image built 2026-08-25 carries AmberTools 26.0 and
+  Gromacs 2026.3, while panacea's native environment is on Gromacs
+  2025.4 -- a different major version against the same htpolynet.
+
+  Unpinning is deliberate and mostly right: pinning would freeze the image on
+  old Gromacs and defeat the point of a weekly rebuild. The gap is that
+  nothing *records* what a given image resolved to, so the versions are
+  discoverable only by running `htpolynet info` inside it and writing the
+  answer down by hand. The better of two candidates is an image
+  **label** carrying a `conda list` export, written at build time: `docker
+  inspect` then answers the question without running the image, so the record
+  survives reaching someone who cannot run the container at all -- a reviewer,
+  an archive, a future reader holding only the digest. The alternative, making
+  `htpolynet info` machine-readable so a build can capture it, requires the
+  image to still be runnable, which is the weaker guarantee. This is the same
+  requirement as the build manifest below, one layer further down -- what
+  produced this build, all the way to the compilers.
+
+  Raised by the calibration study, which found the 2025.4/2026.3 split only
+  because it went looking after an unrelated prompt.
+
 - **Retire `ghcr.io/abramsgroup/htpolynet`.** Superseded by the
   `cameronabrams` package; still public and still serving a June image to
   anyone with an old link.
@@ -152,33 +150,6 @@ Coverage as of the last measurement: **38.8%** overall.
   cyanate-ester bridge series meant doing (a) and (b) by hand in a throwaway
   RDKit script, which is exactly the work a user should not have to
   reinvent.
-- **The bundled Claude skill only reaches people working in a clone.**
-  `.claude/skills/htpolynet/` is picked up when the working directory is the
-  repository, which covers contributors and anyone who cloned to run the
-  examples -- but not the ordinary user who `pip install`s or
-  `conda install`s htpolynet and works in their own project directory, which
-  is most of them. Whether to ship it inside the package is undecided.
-
-  Two things to settle before doing so, neither obvious:
-
-  1. **The skill would be broken as written.** Its central move is "read
-     `docs/source/user-guide/building-a-system.rst`", a repo path that does
-     not exist for an installed user. A shipped version would have to point
-     at the Read the Docs URL instead, or the guide would have to ship as
-     package data. The first is simpler and goes stale differently -- an RTD
-     link tracks `latest`, so an installed 2.3.0 would send its reader to
-     documentation for whatever is current.
-  2. **Delivery.** A skill file inside a wheel does nothing on its own;
-     something has to place it where the tool looks. An `htpolynet skill
-     --install` subcommand copying it into the user's `~/.claude/skills/`
-     is the obvious mechanism, and is also the point at which a scientific
-     package starts carrying vendor-specific tooling and an install-time
-     side effect on a directory it does not own.
-
-  Worth weighing against simply doing nothing: the procedural guide the skill
-  points at is on Read the Docs already, and an agent that reads
-  documentation gets the same content without any of this.
-
 - **Generated topologies cannot be compared byte-wise, because ParmEd
   stamps them.** Every `.top` htpolynet writes opens with a ParmEd header
   recording the invoking user, the host, and the date:
@@ -326,10 +297,37 @@ Coverage as of the last measurement: **38.8%** overall.
   example anneals at a 500 K peak, and the measured *T*:sub:`g` for this
   system is 487.9 K. That is 12.1 K above the glass transition, for 80 ps.
   The Tg ladder that produced the relaxed value spent 15,785 ps above
-  *T*:sub:`g`, peaking 112 K above it -- 197x the time, in the only regime
-  where a crosslinked network moves at all. Lengthening an anneal that sits
-  12 K above *T*:sub:`g` extends a process that barely moves anything, so
-  the lever is the peak temperature, not the duration.
+  *T*:sub:`g`, peaking 112 K above it -- 197x the time, in the regime where
+  a crosslinked network actually moves. Lengthening an anneal that sits 12 K
+  above *T*:sub:`g` extends a process that barely moves anything, so the
+  lever is the peak temperature, not the duration.
+
+  **But raising the peak is unlikely to close the gap entirely.** Two
+  structures of the same network were held for 5 ns at a 480 K setpoint
+  that thermostatted to 477.1 K -- about 11 K *below* the measured
+  *T*:sub:`g`, and far longer than the 80 ps the example spends near it.
+  Relaxation there is fast at first and then stops: about 87% of an
+  initial 34.8 kg/m³ density gap -- the gap measured over the first 200 ps
+  -- closes within 3 ns, and the remaining 4.25 kg/m³ persists at
+  7.2 sigma, with a last-half trend of +0.030 kg/m³/ns, i.e. not decaying.
+  (State the baseline and the window whenever this number is quoted: the
+  same data give 83.5-87.8% across the defensible choices of each, so a
+  bare percentage is not a fact.)  So heat and time buy most of the
+  relaxation quickly and then buy nothing, and a residual difference
+  survives that a longer anneal at this scale does not appear able to
+  remove.  Whatever replaces the current anneal should
+  therefore be argued as a large improvement, not as a fix; an entry
+  promising equilibration would oversell what was measured.
+
+  Note what that hold also says about *T*:sub:`g` itself: **relaxation does
+  not switch off at the glass transition**, it slows continuously through
+  it.  A transition 20-34 K wide by experiment means 11 K below
+  *T*:sub:`g` is inside the transition, not deep in the glass, so fast
+  early relaxation there is expected rather than anomalous.  This does not
+  soften the argument above -- the 197x figure is unchanged and a peak well
+  clear of the transition is still the lever -- but it does mean *T*:sub:`g`
+  is a soft kinetic boundary for this material, which any protocol
+  expressed relative to it has to accommodate.
 
   **Untested.** Nobody has yet built with a hotter anneal and compared it
   against the melt-and-recool value, which is the experiment that would

{htpolynet-2.3.1 → htpolynet-2.4.0}/docker/Dockerfile

@@ -51,6 +51,14 @@ COPY . /htpolynet
 WORKDIR /htpolynet
 RUN pip install --no-cache-dir .
 
+# The commit this image was built from.  There is no git in the image and no
+# .git beside the installed package, so without this an image cannot say what
+# code it contains -- and its version string is actively misleading between
+# releases, since the weekly rebuild builds from main HEAD.  Declared after the
+# expensive layers so that a changed sha does not invalidate the mamba cache.
+ARG HTPOLYNET_COMMIT=unknown
+ENV HTPOLYNET_COMMIT=${HTPOLYNET_COMMIT}
+
 # Pre-create HOME for the unprivileged user the entrypoint drops to.  When
 # compose.yml mounts a named volume here, Docker initializes the fresh volume
 # from this directory and preserves the 0777 mode.

{htpolynet-2.3.1 → htpolynet-2.4.0}/docs/source/user-guide/container-usage.rst

@@ -99,6 +99,38 @@ The ``compose.yml`` file mounts the current directory into the container as
 ``/work`` and runs the process as your host user, so all output files are
 written with your own ownership.
 
+.. admonition:: Which code is in your image?
+   :class: note
+
+   ``htpolynet info`` reports the exact commit the image was built from, which
+   is baked in at build time.  This matters because ``:latest`` moves: besides
+   moving on every release, it is rebuilt weekly from ``main`` to pick up new
+   Gromacs and AmberTools builds, so an image tagged ``:latest`` is frequently
+   built from a commit *after* the last release and its version number alone
+   will not tell you that.
+
+   For anything whose provenance you need to be able to state later -- a
+   published result, a long campaign you want to keep consistent -- pull by
+   digest or by the per-commit tag rather than ``:latest``, and record what
+   you pulled::
+
+     $ docker pull ghcr.io/cameronabrams/htpolynet@sha256:<digest>
+
+   Every build is also pushed as ``ghcr.io/cameronabrams/htpolynet:<commit-sha>``.
+
+   Note that the image pins more than the ``htpolynet`` code.  Gromacs and
+   AmberTools are installed unpinned from conda-forge at build time, so two
+   images built days apart can carry different versions of either while
+   running identical ``htpolynet`` code -- and a charge method or an
+   integrator is not something you want silently varying across a campaign.
+   Two distinct habits protect against this and are worth keeping apart:
+   **pulling once** and reusing that image gives a campaign a constant tool
+   chain, while **recording the digest** is what lets you say afterwards what
+   that tool chain was.  Doing only the first leaves you consistent but unable
+   to state what you did; doing only the second leaves every fresh pull free
+   to move under you.  ``htpolynet info`` prints the AmberTools and Gromacs
+   versions actually present, so record its output alongside the digest.
+
 Running example shell scripts
 """""""""""""""""""""""""""""
 

{htpolynet-2.3.1 → htpolynet-2.4.0}/docs/source/user-guide/usage.rst

@@ -21,6 +21,7 @@ Subcommand           Description
 ``analyze``          Perform ``gmx``-style analyses of trajectories generated by post-build MD simulations
 ``gen-slurm-script`` Emit a SLURM batch script that runs ``htpolynet run`` for a given config
 ``make-viz``         Regenerate VMD visualization files (``.viz.psf`` + ``.viz.tcl``) from an existing ``top`` + ``gro`` pair
+``setup-claude``     Install htpolynet's Claude Code skill so an agent can drive htpolynet
 ==================== ========================
 
 ``htpolynet <subcommand> -h`` provides subcommand-level help. 
@@ -511,4 +512,28 @@ The main ``.viz.tcl`` sources this file when it exists, so the macros are availa
   # composable with the rest of VMD's selection language
   mol modselect 0 top "THT and not hydrogen"
 
-The residue-level view is untouched — selections like ``resname TBO`` or ``resname IPD`` still work — the constituent macros are an *additive* layer.
+The residue-level view is untouched — selections like ``resname TBO`` or ``resname IPD`` still work — the constituent macros are an *additive* layer.
+
+``htpolynet setup-claude``
+!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+``setup-claude`` installs the skill bundled with the package, which teaches Claude Code how to drive ``htpolynet``: start from the nearest example, describe monomers in their active form, check a config before spending compute, and recognize the failure modes that are known rather than mysterious.
+
+.. code-block:: console
+
+    $ htpolynet setup-claude -h
+
+    usage: htpolynet setup-claude [-h] [--skills-dir SKILLS_DIR] [--force]
+
+    options:
+      -h, --help            show this help message and exit
+      --skills-dir SKILLS_DIR
+                            skills directory to install into (default: ~/.claude/skills);
+                            use ./.claude/skills to scope the skill to one project
+      --force               overwrite an existing installed skill
+
+By default the skill goes to ``~/.claude/skills/htpolynet/SKILL.md``, where Claude Code finds it from any working directory.  Pass ``--skills-dir ./.claude/skills`` to scope it to a single project instead.
+
+Nothing is installed automatically: installing ``htpolynet`` never writes to ``~/.claude/``.  Re-run ``setup-claude --force`` after upgrading to pick up the current version of the skill, which otherwise stays as it was when you first installed it.
+
+Working inside a clone of the repository needs none of this --- ``.claude/skills/`` there is a symbolic link to the same file, so the skill is already in scope.

{htpolynet-2.3.1 → htpolynet-2.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "htpolynet"
-version = "2.3.1"
+version = "2.4.0"
 authors = [
   { name="Cameron F Abrams", email="cfa22@drexel.edu" },
 ]

{htpolynet-2.3.1 → htpolynet-2.4.0}/src/htpolynet/cli.py

@@ -5,11 +5,15 @@ Author: Cameron F. Abrams <cfa22@drexel.edu>
 
 import logging
 import os
+import shutil
 import textwrap
 
 import argparse as ap
 import yaml
 
+from importlib.resources import files as pkg_files
+from pathlib import Path
+
 from .analysis.analyze import analyze
 from .analysis.plot import plots
 from .analysis.postsim import postsim
@@ -119,6 +123,37 @@ def fetch_example(args):
     _fetch_one(depot, fullname)
 
 
+def setup_claude(args: ap.Namespace):
+    """Handles the setup-claude subcommand.
+
+    Copies the bundled skill into the user's skills directory.  This runs only
+    when the user asks for it; installing the package never touches
+    ``~/.claude/``.
+
+    Args:
+        args (argparse.Namespace): parsed arguments
+    """
+    # Resolve through htpolynet.resources, which is a real package; the claude/
+    # subdirectory carries no __init__.py, matching every other resource
+    # subdirectory.
+    source = pkg_files('htpolynet.resources').joinpath('claude', 'SKILL.md')
+    if not source.is_file():
+        raise FileNotFoundError(f'Bundled skill not found at {source}')
+
+    skill_dir = Path(args.skills_dir).expanduser() / 'htpolynet'
+    target = skill_dir / 'SKILL.md'
+
+    if target.exists() and not args.force:
+        print(f'{target} already exists; re-run with --force to overwrite it')
+        return
+
+    skill_dir.mkdir(parents=True, exist_ok=True)
+    with source.open('rb') as fh, open(target, 'wb') as out:
+        shutil.copyfileobj(fh, out)
+    print(f'Written: {target}')
+    print('Claude Code picks the skill up on its next session in any directory.')
+
+
 def _add_run_options(p, loglevel='debug'):
     """Adds run options (no positional config) shared by run and gen-slurm-script."""
     p.add_argument('-lib',type=str,default='lib',help='local user library of molecular structures and parameterizations')
@@ -257,6 +292,7 @@ def cli():
         ('analyze',          analyze,          "perform 'gmx <command>' style analyses specified in the config file"),
         ('gen-slurm-script', gen_slurm_script, 'generate a SLURM submission script for running htpolynet on a cluster'),
         ('make-viz',         make_viz,         'regenerate VMD viz files (.viz.psf + .viz.tcl) from an existing gromacs top + gro pair'),
+        ('setup-claude',     setup_claude,     "install htpolynet's Claude Code skill so an agent can drive htpolynet"),
     ]
 
     parser = ap.ArgumentParser(description=textwrap.dedent(banner_message),formatter_class=ap.RawDescriptionHelpFormatter)
@@ -291,6 +327,10 @@ def cli():
     cp['make-viz'].add_argument('-grx', type=str, default=None, help='input htpolynet .grx (default: auto-detect <gro-stem>.grx; needed for the constituent-selection macros)')
     cp['make-viz'].add_argument('-prefix', type=str, default=None, help='output basename; the .viz.psf, .viz.tcl, and .viz.macros.tcl are written next to the input gro (default: stem of -gro)')
 
+    cp['setup-claude'].add_argument('--skills-dir', type=str, default='~/.claude/skills',
+                                    help='skills directory to install into (default: %(default)s); use ./.claude/skills to scope the skill to one project')
+    cp['setup-claude'].add_argument('--force', default=False, action='store_true', help='overwrite an existing installed skill')
+
     _add_analysis_args(cp['postsim'])
     _add_analysis_args(cp['analyze'])
 

{htpolynet-2.3.1 → htpolynet-2.4.0}/src/htpolynet/external/software.py

@@ -97,8 +97,13 @@ def _get_git_commit():
     report.  Reporting 'unknown' there leaves a build with no way to answer
     "what code produced this" from inside itself, which is exactly the
     question the parameterization records exist to answer for molecules.
-    Fall back to the installed distribution version, which for a released
-    install maps to a tag and is the honest answer.
+    The published container bakes the commit it was built from into
+    ``HTPOLYNET_COMMIT``, which is consulted next: the image's version string
+    alone is misleading between releases, since the scheduled rebuild builds
+    from ``main`` HEAD and reports whatever ``pyproject.toml`` last said.
+
+    Failing both, fall back to the installed distribution version, which for a
+    released install maps to a tag and is the honest answer.
     """
     global git_commit
     src = os.path.dirname(__file__)
@@ -118,6 +123,10 @@ def _get_git_commit():
             return
     except Exception:
         pass
+    baked = os.environ.get('HTPOLYNET_COMMIT', '').strip()
+    if baked and baked != 'unknown':
+        git_commit = f'{baked[:7]} (baked in at image build)'
+        return
     try:
         from importlib.metadata import version, PackageNotFoundError
         try:

htpolynet-2.4.0/src/htpolynet/resources/claude/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: htpolynet
+description: Build crosslinked polymer systems with htpolynet — authoring a run configuration, parameterizing monomers, running a cure, and reading the results. Use when the task involves an htpolynet YAML config, the `htpolynet` command (run, input-check, gen-slurm-script, plots, postsim, analyze, make-viz), a monomer's active form or sacrificial hydrogens, a cure that stalls below its target conversion, or sizing an htpolynet build for a cluster.
+---
+
+# Working with htpolynet
+
+htpolynet builds crosslinked polymer systems: it parameterizes monomers with
+GAFF, packs them, and then *cures* the system by repeatedly forming bonds
+between reactive atoms until it reaches a target conversion. The output is a
+Gromacs topology and coordinate pair plus the analysis to characterize it.
+
+## The working loop
+
+1. Fetch the bundled example closest in **reaction topology** and run it
+   unmodified once.
+2. Edit it into your system. Describe monomers in their **active form**.
+3. `htpolynet input-check <cfg>` — fast, touches nothing, reports the atom
+   count you size a core request against.
+4. `htpolynet run <cfg>`, in the background, or via a batch script.
+5. `htpolynet plots build --proj proj-0` to see what you got.
+
+## Start from an example, never from an empty file
+
+A working configuration is a few hundred lines and most of it is not
+chemistry-specific. Writing one from scratch is the slowest route and the one
+that produces silent errors.
+
+```bash
+htpolynet fetch-example 1     # linear chain growth (polystyrene)
+htpolynet fetch-example 2     # A2 + B4 thermoset (bisGMA/styrene)
+htpolynet fetch-example 3     # amine + epoxy (PACM/DGEBA)
+htpolynet fetch-example 6     # cyclotrimerization (cyanate ester)
+```
+
+Pick by **reaction topology**, not by chemistry. Building a step-growth
+thermoset from a difunctional and a tetrafunctional monomer? Example 2 beats
+an example that shares a functional group but polymerizes by chain growth.
+
+Run it unmodified first. That confirms the toolchain and gives you a
+known-good log to diff against when your own config misbehaves.
+
+## Monomers are described in their active form
+
+The most common conceptual error, and it produces a build that completes and
+is wrong rather than one that fails.
+
+htpolynet conserves valence: when two atoms bond, each gives up a
+**sacrificial hydrogen**. So you do not describe the textbook monomer — you
+describe the monomer with its reactive sites already saturated. Styrene is
+described as ethylbenzene.
+
+Prefer SMILES written directly into `constituents` with RDKit atom-map
+labels, which name reactive atoms by chemical identity rather than by file
+index:
+
+```yaml
+constituents:
+  STY:
+    smiles: "c1ccccc1[CH2:1][CH3:2]"
+    reactive_atoms: {1: C1, 2: C2}
+```
+
+In SMILES bracket atoms the hydrogen count is explicit: `[C:1]` means *zero*
+implicit hydrogens. For an sp³ carbon you almost always want `[CH2:1]` or
+`[CH3:1]`. A wrong count usually surfaces much later as a missing GAFF angle
+parameter in `tleap`, a long way from its cause.
+
+## Check before spending compute
+
+`htpolynet input-check <cfg>` reports the initial atom count in about a
+second. Run it every time you change monomer counts.
+
+Know what it does **not** check. It does not verify that
+`symmetry_equivalent_atoms` groups really are topologically equivalent, that
+A2 + B3 site counts balance, or that `desired_conversion` is reachable given
+the monomer counts. Those are silent failure modes: a wrong symmetry group
+generates reaction templates the cure stage never matches, and the build
+spends its full wall-clock reaching a conversion it could never have reached.
+
+## Running
+
+Builds are slow — production systems are hours to a day. Run them in the
+background, or generate a batch script rather than writing one:
+
+```bash
+htpolynet gen-slurm-script <cfg>
+```
+
+Size the core request from the `input-check` atom count.
+
+**If you are using the container image, target CPU partitions.** Its Gromacs
+comes from conda-forge, built against OpenCL, which Gromacs no longer uses to
+drive NVIDIA devices. The image cannot use a GPU: `--gres=gpu` and `--nv` buy
+nothing and may cost queue time.
+
+Parameterization runs first and is cached across projects and directories.
+The first run of a new chemistry pays several minutes per species; later runs
+reuse it. Editing a monomer's structure **without renaming it** silently
+reuses the old parameterization — `--force-parameterization` rebuilds.
+
+## Builds are not reproducible run to run
+
+There is no seed control. Conformer selection, the per-bond probability test,
+and Gromacs velocity generation are all unseeded, so two runs of one config
+diverge. Convenient in one direction — independent replicas of a
+quenched-disorder ensemble come free, and each `htpolynet run` in the same
+base directory makes its own project directory — but an exact rebuild is not
+available. Record the commit (`htpolynet info`) when the result matters.
+
+## Reading the results
+
+```bash
+htpolynet plots build --proj proj-0     # traces, reaction graph, cluster sizes
+htpolynet make-viz -top final.top -gro final.gro
+htpolynet postsim postsim.yaml --proj proj-0
+htpolynet plots post --proj proj-0      # E and Tg
+htpolynet analyze analyze.yaml --proj proj-0
+```
+
+**The postcure NPT plateau is not an equilibrated density.** It is an
+under-relaxed structure, and on the bundled cyanate-ester example it sits
+about 2.3% below what the same system gives after a melt and slow re-cool.
+Do not report a plateau density as a force-field result.
+
+## Subcommand routing
+
+| Intent | Command |
+|---|---|
+| Build a system | `htpolynet run <cfg>` |
+| Size it before queueing | `htpolynet input-check <cfg>` |
+| Stop after parameterization | `htpolynet run --param-only <cfg>` |
+| Submit to a cluster | `htpolynet gen-slurm-script <cfg>` |
+| Plot a finished build | `htpolynet plots build --proj <dir>` |
+| Post-build MD / analysis | `htpolynet postsim`, `htpolynet analyze` |
+| Rebuild VMD viz files | `htpolynet make-viz` |
+| Report the environment | `htpolynet info` |
+
+## When something goes wrong
+
+- **The cure stalls below the target conversion.** Usually a reaction
+  template that never matches: suspect `symmetry_equivalent_atoms` and
+  reactive-atom names before suspecting the chemistry.
+- **A `tleap` error about a missing parameter.** Usually an atom typed
+  wrongly from a hydrogen-count error in a SMILES bracket atom.
+- **Results that do not match the config you are reading.** Suspect a stale
+  cache entry: a structure edit without a rename.
+- **A build that dies during cure.** `-restart` is experimental and currently
+  broken at the cure stage, which is the worst place to lose work. Treat a
+  dead cure as a restart from the beginning.
+- **Anything else.** `htpolynet info` reports the versions of every external
+  tool the build depends on; include its output in any bug report.
+
+## Do not
+
+Do not write workarounds into this file. If the tool surprises a user in a
+way that requires a ritual to avoid, that is a bug: fix it in code, or file
+it with enough context to act on later. A skill that teaches people to route
+around a defect keeps the defect.
+
+## Full reference
+
+<https://htpolynet.readthedocs.io/> — in particular the user guide's
+*Building a System, Start to Finish*, which this file condenses, and
+*Molecular Structure Inputs*, which explains the active form with pictures.