hannahbaumann · Nov 4, 2026 · Oct 29, 2026 · Oct 29, 2026 · Oct 29, 2026 · Oct 30, 2026
diff --git a/docs/cookbook/dumping_transformation.rst b/docs/cookbook/dumping_transformation.rst
@@ -1,7 +1,7 @@
 .. _dumping_transformations:
 
-Dumping a ``Transformation`` to JSON
-====================================
+Dump a ``Transformation`` to JSON
+=================================
 
 If you're trying to run a full campaign of simulations representing an
 alchemical network, we generally recommend saving objects using our storage

diff --git a/docs/cookbook/index.rst b/docs/cookbook/index.rst
@@ -1,168 +1,77 @@
 .. _cookbooks:
 
-Cookbook
-========
+How-To Guides
+=============
 
-This section describes common tasks involving the OpenFE Python API.
+These guides show how to carry out specific tasks with **openfe**, mostly using the Python API.
+For the concepts behind each step, see the :doc:`User Guide </guide/index>`.
+To run a transformation with ``openfe quickrun``, see :ref:`userguide_quickrun`.
 
-The :any:`OpenFE CLI<cli-reference>` provides a simple way to perform the most common procedures for free energy calculations, but does not provide much flexibility for fine-tuning your approach or combining OpenFE with other tools. The :any:`Python API<api>` allows that flexibility, but using it is more complex. This cookbook breaks down common steps that would be implemented in Python to help navigate that complexity.
-
-.. note:: This section is a work-in-progress.
+.. TODO: remove the quickrun sentence above once moved to "Running calculations"
 
 .. module:: openfe
     :noindex:
 
-The Basic Workflow
-------------------
-
-The typical way to use the Python API is to load a number of molecules you want to calculate free energies of, construct a :class:`LigandNetwork` connecting them in an efficient way, and then combine that with information for how each ligand should be simulated to construct an :class:`AlchemicalNetwork`, which specifies the entire simulation campaign. This provides a lot of flexibility in how molecules are specified, mapped, connected, and simulated, without exposing a great deal of complexity. OpenFE recommends this workflow for most users.
-
-.. container:: deflist-flowchart
-
-    * Setup
-        - .. container:: flowchart-sidebyside
-
-            -   -
-                    .. rst-class:: flowchart-spacer
-                -
-
-                    .. rst-class:: arrow-down arrow-from-nothing
-                - :any:`choose_protocol`
-
-                - :class:`Protocol`
-                    Simulation procedure for an alchemic mutation.
-
-                    .. rst-class:: arrow-down arrow-tail arrow-combine-right
-                -
-
-            -   -
-                    .. rst-class:: width-8
-                -  Chemical component definition
-                    SDF, PDB, RDKit, OpenFF Molecule, solvent spec, etc.
-
-                - .. container:: flowchart-sidebyside
-
-                    - .. rst-class:: width-3
-
-                        -
-
-                            .. rst-class:: arrow-down arrow-multiple
-                        - :any:`Loading proteins`, :any:`Defining solvents`
-
-                        - :class:`SolventComponent` and :class:`ProteinComponent`
-                            Other chemical components needed to simulate the ligand.
-
-                            .. rst-class:: arrow-down arrow-multiple arrow-tail arrow-combine
-                        -
-
-                    -   - .. container:: flowchart-sidebyside
-
-                            - .. rst-class:: width-5
-
-                                -
-                                    .. rst-class:: arrow-down arrow-multiple
-                                - :any:`Loading small molecules`
-
-
-                                - :class:`SmallMoleculeComponent`
-                                    The ligands that will be mutated.
-
-                            - .. rst-class:: width-3
-
-                                -
-                                    .. rst-class:: flowchart-spacer
-                                -
-
-                                - Orion/FEP+
-                                    Network from another tool.
-
-
-                        - .. container:: flowchart-sidebyside
-
-                            - .. rst-class:: width-2
-
-                                -
-                                    .. rst-class:: arrow-down arrow-multiple
-                                - :any:`generate_ligand_network`
-
-                            - .. rst-class:: width-2
-
-                                -
-                                    .. rst-class:: arrow-down arrow-multiple
-                                - :any:`hand_write_ligand_network`
-
-                            - .. rst-class:: width-1
-
-                                -
-                                    .. rst-class:: arrow-down arrow-tail arrow-multiple arrow-combine-right
-                                -
-
-                                    .. rst-class:: flowchart-spacer
-                                -
+.. toctree::
+   :maxdepth: 1
+   :caption: Setting up chemical systems
 
-                            - .. rst-class:: width-3
+   loading_molecules
+   user_charges
+   bespoke_parameters
 branch="main", 
 branch="main", 
+   packmol_memgen_setup
 
-                                -
-                                    .. rst-class:: arrow-down arrow-tail arrow-combine-left
-                                -
+.. TODO: merge cofactors_rbfe into loading_molecules,
+   "Create a ChemicalSystem", "Specify custom force fields", OpenFold3 notebooks.
 
-                                    .. rst-class:: arrow-down arrow-head flowchart-spacer
-                                - :any:`network_from_orion_fepp`
+.. toctree::
+   :maxdepth: 1
+   :caption: Planning: Ligand networks
 
-                        - :class:`LigandNetwork <openfe.setup.LigandNetwork>`
-                            A network of ligand transformations.
+   generate_ligand_network
+   hand_write_ligand_network
+   network_from_orion_fepp
+   ligandnetwork_vis
 
-                        - .. container:: flowchart-sidebyside
+.. TODO: add howto on scorers
 
-                            -   -
-                                    .. rst-class:: arrow-down arrow-tail arrow-combine-left width-4
-                                -
+.. toctree::
+   :maxdepth: 1
+   :caption: Planning: Protocols and alchemical networks
 
-                            -   -
-                                    .. rst-class:: arrow-cycle width-4
-                                -
+   choose_protocol
+   rfe_alchemical_planners
+   create_alchemical_network
 
-                                - :any:`ligandnetwork_vis`
+.. TODO: add "Customize CLI planning with YAML" (from guide/cli/cli_yaml) and move the
+   how-to parts of guide/setup/defining_protocols into choose_protocol.
 
+.. toctree::
+   :maxdepth: 1
+   :caption: Running calculations
 
-            .. rst-class:: arrow-down arrow-head
-        - :any:`create_alchemical_network`
+   dumping_transformation
 
-        - :class:`AlchemicalNetwork`
-            A complete simulation campaign.
+.. TODO: add: run a transformation with quickrun,
+   run repeats in parallel, run on a SLURM cluster, resume interrupted calculations and
+   share a GPU using NVIDIA MPS (from guide/execution/quickrun_execution), and task-based
+   execution.
 
-      .. rst-class:: arrow-down
-    * :any:`dumping_transformations`
+.. toctree::
+   :maxdepth: 1
+   :caption: Working with results
 
-    * Run
-        - :any:`openfe quickrun <cli_quickrun>`
-            OpenFE recommends using the ``openfe quickrun`` CLI command to execute a transformation.
+   jq_inspection
 
-      .. rst-class:: arrow-down
-    *
+.. TODO: add "Gather free energy results" and "Load results in Python" (from
+   guide/results/working_with_results), "Analyze an RBFE network with cinnabar" (from
+   guide/results/working_with_networks) and "Visualize trajectories with openfe_analysis".
+.. TODO: merge dumping_transformation and jq_inspection into a single
+   "Save and inspect OpenFE JSON files" how-to.
 
-    * Gather
-        - :any:`openfe gather <cli_gather>`
-            OpenFE recommends using the ``openfe gather`` CLI command to collect the results of a transformation.
+.. toctree::
+   :maxdepth: 1
+   :caption: Repairing and extending networks
 
-List of Cookbooks
------------------
+   repairing_broken_networks
 
-.. toctree::
-    :maxdepth: 1
-
-    loading_molecules
-    dumping_transformation
-    jq_inspection
-    choose_protocol
-    generate_ligand_network
-    rfe_alchemical_planners
-    network_from_orion_fepp
-    hand_write_ligand_network
-    ligandnetwork_vis
-    create_alchemical_network
-    user_charges
-    bespoke_parameters
-    repairing_broken_networks
-
-
diff --git a/docs/cookbook/jq_inspection.rst b/docs/cookbook/jq_inspection.rst
@@ -1,7 +1,8 @@
 .. _jq_inspection:
 
-Using ``jq`` to inspect OpenFE JSONs
-==============================================
+Use ``jq`` to inspect OpenFE JSONs
+==================================
+
 Sometimes you may want to get a sense of the contents of JSON files, but the files are too unwieldy to inspect one-by-one in a code editor.
 
 `jq <https://github.com/jqlang/jq>`_ is a helpful command-line tool that we recommend for for quickly inspecting JSON files.

diff --git a/docs/cookbook/packmol_memgen_setup.nblink b/docs/cookbook/packmol_memgen_setup.nblink
@@ -0,0 +1,3 @@
+{
+   "path": "../ExampleNotebooks/membranes/packmol_memgen_setup.ipynb"
+}
diff --git a/docs/guide/cli/index.rst b/docs/guide/cli/index.rst
@@ -13,3 +13,5 @@ into non-Python workflows.
 .. toctree::
    cli_basics
    cli_yaml
+
+.. TODO: add a "How-to guides" box listing the CLI YAML how-to.
diff --git a/docs/guide/execution/index.rst b/docs/guide/execution/index.rst
@@ -13,3 +13,10 @@ then :ref:`reading on the available Python functions<reference_execution>`.
    quickrun_execution
    task_based_execution
    execution_theory
+
+.. admonition:: How-to guides
+
+   * :doc:`/cookbook/dumping_transformation`
+
+.. TODO: add the Running calculations how-tos (quickrun, repeats in parallel, SLURM,
+   resuming, NVIDIA MPS, task-based execution) to this box.