ycleptic 2.2.2__tar.gz → 2.4.0__tar.gz

{ycleptic-2.2.2 → ycleptic-2.4.0}/.gitignore

@@ -85,6 +85,16 @@ tests/test_set/console-out.txt
 tests/test_set/ydoc.rst
 tests/test_set/ydoc/
 tests/test_set/rcfile.yaml
+tests/test_set/spec-check-base.yaml
+tests/test_set/freekey_base.yaml
+tests/test_set/freekey_mut.yaml
+tests/test_set/vt_base.yaml
+tests/test_set/reclist_base.yaml
+tests/test_set/reclist_mut.yaml
+tests/test_set/alias_base.yaml
+tests/test_set/listmode_base.yaml
+tests/test_set/both_base.yaml
+tests/test_set/type_base.yaml
 
 # PyBuilder
 target/
@@ -106,6 +116,11 @@ ipython_config.py
 #   install all needed dependencies.
 #Pipfile.lock
 
+# uv
+#   ycleptic is a library, not an application, so its resolved dependency set
+#   is not pinned in the repo; `uv run` regenerates uv.lock on demand.
+uv.lock
+
 # PEP 582; used by e.g. github.com/David-OConnor/pyflow
 __pypackages__/
 

{ycleptic-2.2.2 → ycleptic-2.4.0}/CHANGELOG.md

@@ -5,6 +5,41 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [2.4.0] - 2026-09-08
+
+### Added
+- A `dict` attribute may declare `value_attributes` instead of `attributes`, describing the schema every *value* of a mapping must satisfy while leaving the keys for the user to invent. Sections keyed by names only the user knows — molecules in a formulation, named reactions — previously had to be declared as bare `type: dict` and passed through with no validation, no defaults and no generated documentation; they can now be specified as fully as any other attribute. Errors inside a value name the entry they came from, e.g. `under 'constituents[STY]'`
+- `key_text`, a one-line description of what a free-form key means, rendered by `yclept make-doc` and interactive help. A free-key mapping has no list of legal keys for a user to read, so this is the only thing telling them what a key is
+- `list_defaults: append | replace` on a `list` attribute, controlling what happens to a declared `default` when the user supplies a list of their own. `append` is the default and is the historical behavior. Under `replace` the user's list is used verbatim, the default applying only when the attribute is omitted entirely
+- Generated documentation and interactive help now state, wherever a non-empty list default is shown, whether a user-supplied list is added to it or replaces it
+- `value_type`, the scalar counterpart to `value_attributes`: a `dict` or `list` whose elements are plain scalars rather than attribute blocks can now declare `value_type: str | int | float | bool` and have every element type-checked. Note that `value_type: str` is genuinely enforced, unlike a declared `type: str` attribute, which is validated through `choices`
+- `value_attributes` now also applies to a `list`, where it means every *item* satisfies the schema. This covers a list of flat, multi-key records that all look alike (`- ensemble: npt` with `temperature` and `ps` beside it), which the existing tagged-task idiom — where each item is a single-key mapping naming which attribute it is — cannot express. Per-item defaults are filled in and errors name the item, e.g. `under 'stages[1]'`. Tagged-task lists, declared with `attributes`, are unchanged
+
+### Fixed
+- A base config's declared `default` is no longer handed to the user's config by reference, so loading a config can no longer rewrite the schema it was validated against. `special_update` writes into its first argument, which was the spec's own default object, so a user's values were merged into the base config; a `dict` or `list` default for an omitted attribute was likewise handed out as the schema's own object, and ordinary consumer code mutating its config grew the schema's default. `make_default_specs` was affected both ways: it reported the user's values as defaults after any load, and the dict it returned aliased the spec. Every default is now copied before it is handed out
+
+  **This changes observable behavior in one narrow case.** `update_user` does a top-level `dict.update`, so passing a `dict` attribute replaces that attribute's value entirely. Sub-keys set by an earlier `update_user` used to survive that replacement, but only because they had been merged into the schema's default; now they do not. Top-level attributes the new data does not mention are untouched either way. Generated documentation built from a `Yclept` that carries a user config also no longer renders that user's values as documented defaults
+- A `choices` violation now names the enclosing block rather than repeating the attribute's own name, so the message reads `Attribute 'ensemble' of 'stages[0]'` instead of `Attribute 'ensemble' of 'ensemble'`
+- `yclept check-spec` and the load-time spec check learned the new vocabulary, and report several further declarations that do nothing:
+  - more than one of `attributes`, `value_attributes` and `value_type` on a single node — a node describes what is under it exactly one way
+  - `value_attributes` or `value_type` on an attribute that is neither a `dict` nor a `list`
+  - an unrecognized `value_type`
+  - `key_text` on a node that declares neither `value_attributes` nor `value_type`, and `key_text` on a `list`, whose elements are positional and have no keys
+  - `list_defaults` on a non-`list` attribute, on a `list` that declares `attributes` (a tagged-task list never merges a default), and an unrecognized `list_defaults` value
+
+  Attribute specs nested under `value_attributes` are checked too, with `[*]` in the reported path marking the step through a free-form key
+
+## [2.3.0] - 2026-08-13
+
+### Added
+- Base config specifications are now checked when they are loaded, and any declaration ycleptic ignores is reported: a key outside the recognized set (`options:` where `choices:` was meant), an unrecognized `type:` name (`string` instead of `str`), an attribute with no declared type, and `choices` on a non-`str` attribute, which is not enforced. Such a declaration silently does nothing, so an attribute its author believes is constrained may in fact accept any value. Findings are issued as a `YclepticSpecWarning` and the config still loads; `Yclept(..., strict_spec=True)` raises `YclepticError` instead
+- `yclept check-spec <base.yaml>` reports the same findings from the command line and exits nonzero when any are found, so it can gate a CI run
+- `ycleptic.speccheck.check_base_spec`, which returns the findings as a list of strings
+
+### Fixed
+- `yclept make-doc` now renders an attribute's `choices` as "Allowed values" in the generated documentation. Interactive help has always shown them, so generated docs and interactive help disagreed about what the schema allowed
+- An attribute with no declared `type` now reports a clean error naming the attribute, instead of raising `KeyError: 'type'`
+
 ## [2.2.2] - 2026-08-13
 
 ### Added

ycleptic-2.4.0/CLAUDE.md

@@ -0,0 +1,148 @@
+# CLAUDE.md — working notes for ycleptic
+
+Ycleptic turns one YAML file — the **base config**, a schema written as *data* —
+into three things at once: validation of a user's config, a generated Sphinx
+doctree, and an interactive help browser. The whole point is that those three
+never drift apart, because they all read the same file. Keep that invariant in
+mind before adding a feature: **anything that teaches the validator a new trick
+must also teach `make-doc` and `console_help` the same trick**, or the schema
+stops being a single source of truth. The v2.3.0 `choices` fix was exactly this
+bug — interactive help showed allowed values, generated docs did not.
+
+## Layout
+
+    ycleptic/
+      yclept.py       Yclept(UserDict) — the public class; loads base + user,
+                      make_doctree(), console_help(), dump_user(),
+                      make_default_specs()
+      walkers.py      the recursive core: dwalk (validate/fill a dict level),
+                      lwalk (a list of task-items), mwalk (merge an rc/dotfile
+                      base into the app base), make_def (defaults for a subtree)
+      speccheck.py    validates the base config *itself* — the recognized-key
+                      and recognized-type vocabulary lives here
+      makedoc.py      base spec -> RST tree
+      cli.py          `yclept` entry point: make-doc, config-help, check-spec
+      errors.py       YclepticError, YclepticSpecWarning
+      dictthings.py   special_update (list-append / dict-merge semantics)
+      stringthings.py raise_clean, oxford, footer + RST helpers
+      resources/example_base.yaml   the shipped example schema
+      src/__init__.py deprecation shim for the pre-2.3 `ycleptic.src.*` paths
+
+`docs/source/` mirrors this: `usage/` is hand-written prose, `api/` is autodoc
+stubs — a new module needs a new `api/ycleptic.<mod>.rst`.
+
+## Two kinds of validation — don't confuse them
+
+1. **User config vs. base config** — `dwalk`/`lwalk`. Failures are the user's
+   fault. They raise `YclepticError` via `raise_clean()`.
+2. **Base config vs. ycleptic's own vocabulary** — `speccheck.check_base_spec`.
+   Failures are the *schema author's* fault: a key or type name ycleptic does
+   not read, which is therefore silently discarded. These warn
+   (`YclepticSpecWarning`) so existing schemas keep loading;
+   `Yclept(..., strict_spec=True)` promotes them to errors, and
+   `yclept check-spec` exits nonzero so CI can gate on them.
+
+Because a base config is data, **an unrecognized key is not an error, it is a
+no-op** — that is the failure mode speccheck exists to surface. If you add a
+key or type name to the schema vocabulary, add it to `KNOWN_ATTRIBUTE_KEYS`,
+`KNOWN_DOCS_KEYS`, `KNOWN_TOP_KEYS`, or `KNOWN_TYPES` in `speccheck.py` in the
+same change, or `check-spec` will start reporting your own new feature as a
+mistake. Consider adding a `_KEY_ALIASES`/`_TYPE_ALIASES` entry for the
+misspelling people will actually make; anything else falls back to difflib.
+
+## Error convention
+
+Library code never calls `sys.exit`. It calls
+`raise_clean(ValueError(...))`, which re-raises the message as a
+`YclepticError` with `from None` so embedding applications get a clean,
+catchable exception and the CLI gets a traceback-free message. New validation
+failures should follow this — a bare `raise ValueError` leaks a traceback and
+is not part of the documented `try/except YclepticError` contract.
+
+## Typing rules that look like bugs but are deliberate
+
+In `walkers._scalar_type_ok`:
+
+- `bool` is **not** an `int`. A YAML boolean must not satisfy a numeric
+  attribute, so both the `int` and `float` checks explicitly exclude `bool`.
+- an `int` **is** accepted where `float` is declared (widening).
+- a YAML sequence satisfies `tuple` — YAML has no tuple type — and is stored
+  as a real `tuple`.
+- `str` is not type-checked here at all; string attributes are constrained
+  through `choices` (and `case_sensitive`, which casefolds in place).
+- `choices` is only enforced on `str`. Declaring it elsewhere does nothing,
+  which is why speccheck reports it.
+
+Defaults merge, they do not overwrite: a `dict` attribute with no
+subattributes merges the user's value into the default via `special_update`
+(lists append, dicts merge, scalars overwrite); a `list` attribute prepends its
+default (`defaults + I[d]`). Changing this quietly changes behavior for every
+downstream app.
+
+## Conventions
+
+- `I` is the input/user dict parameter throughout `walkers.py`; ruff's `E741`
+  is disabled repo-wide for exactly this reason. Don't rename it piecemeal.
+- Single quotes — `ruff format` is configured with `quote-style = 'single'`,
+  and CI runs `ruff format --check`.
+- Public re-exports in `ycleptic/__init__.py` must follow the `__version__`
+  assignment, so `E402` is ignored there.
+- `__version__` comes from installed package metadata, not a literal; only
+  `pyproject.toml` carries the version, and only `release.sh` edits it.
+
+**A consequence of that last point, which has bitten a downstream consumer.**
+Between releases, `main` carries the *previous* release's version number —
+unreleased work on `main` today still reports `2.3.0`. The code is current; only
+the number lags. Anything that keys on the version rather than the tree cannot
+tell the difference: `uv` and `pip` wheel caches will happily serve a cached
+`2.3.0` artifact built from older source. Symptoms are new features appearing
+absent while the checkout plainly contains them.
+
+When testing a consumer against an unreleased checkout, verify what you actually
+loaded rather than trusting the version:
+
+    python -c "import ycleptic, ycleptic.walkers as w; \
+               print(ycleptic.__file__, hasattr(w, 'subattributes'))"
+
+An editable install, `PYTHONPATH`, or `uv run --project <checkout>` all resolve
+to the working tree; a plain non-editable install of the checkout is the case
+that can be served stale.
+
+`uv run --with <checkout>` is the trap, and it is silent. If the consuming
+project declares `ycleptic>=2.3.0` and the checkout also calls itself `2.3.0`,
+the floor is already satisfied and uv may resolve to the PyPI build instead of
+the path you named. Nothing errors, and the version string is identical either
+way, so the only reliable gate is file content — check `ycleptic.__file__`, or
+probe for a symbol the branch introduced. Observed 2026-09-08 while a downstream
+repo tried to test against an unreleased branch.
+
+## Working commands
+
+    uv run --extra test pytest tests -q      # 52 tests, <1s. NOT tests/unit
+    uv run --extra lint ruff check ycleptic/
+    uv run --extra lint ruff format --check ycleptic/
+    uv run --extra lint mypy ycleptic/
+
+Tests live in one file, `tests/test_set.py` (single `TestYclept` unittest
+class). `tests/conftest.py` chdirs each test into `tests/test_set/`, so tests
+read and write fixture files by bare filename; several test outputs there are
+gitignored. `tests/test_set/test_package/` is a miniature installable package
+used to exercise `make-doc` against a realistic app layout.
+
+CI (`.github/workflows/ci.yaml`) runs pytest on Python 3.9–3.13 plus a lint job.
+The floor is **3.9**, so no `match`, no PEP 604 unions at runtime — every module that
+needs a modern annotation carries `from __future__ import annotations` and
+relies on it.
+
+## Releasing
+
+    scripts/release.sh <version>
+
+It rotates `CHANGELOG.md`'s `[Unreleased]` section, bumps `pyproject.toml`,
+commits, tags, and pushes. **Pushing the tag is what publishes to PyPI.** Never
+hand-roll any of those steps. Write the changelog entries under `[Unreleased]`
+as you go, not at release time.
+
+`pestifer` pins `ycleptic>=2.3.0` and is the only known downstream consumer —
+coordinate with it before a release that moves the floor, and keep the
+`ycleptic.src` deprecation shim until it is confirmed unused.

{ycleptic-2.2.2 → ycleptic-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ycleptic
-Version: 2.2.2
+Version: 2.4.0
 Summary: A YAML-format configuration generator
 Project-URL: Source, https://github.com/cameronabrams/ycleptic
 Project-URL: Documentation, https://ycleptic.readthedocs.io/en/latest/

{ycleptic-2.2.2 → ycleptic-2.4.0}/docs/source/api/ycleptic.rst

@@ -24,6 +24,7 @@ Submodules
    ycleptic.dictthings
    ycleptic.errors
    ycleptic.makedoc
+   ycleptic.speccheck
    ycleptic.stringthings
    ycleptic.walkers
    ycleptic.yclept

ycleptic-2.4.0/docs/source/api/ycleptic.speccheck.rst

@@ -0,0 +1,7 @@
+ycleptic.speccheck module
+=========================
+
+.. automodule:: ycleptic.speccheck
+   :members:
+   :show-inheritance:
+   :undoc-members:

ycleptic-2.4.0/docs/source/usage/the_base_config.rst

@@ -0,0 +1,377 @@
+.. _usage_the_base_config:
+
+The Base Configuration
+========================
+
+The heart of ``ycleptic`` is the base configuration file, which the app developer must write. The base configuration is the developer's expression of what a *user* can configure when they run the developer's app.  Below is an example:
+
+.. code-block:: yaml
+
+  attributes:
+    - name: attribute_1
+      type: dict
+      text: This is a description of Attribute 1
+      attributes:
+        - name: attribute_1_1
+          type: list
+          text: This is a description of Attribute 1.1
+          default:
+            - 1
+            - 2
+            - 3
+        - name: attribute_1_2
+          type: str
+          text: This is a description of Attribute 1.2
+          choices: [valA, valB]
+    - name: attribute_2
+      type: list
+      text: Attribute 2 is interpretable as an ordered list of attributes
+      attributes:
+        - name: attribute_2a
+          type: dict
+          text: Attribute 2a is one possible attribute in a user's list
+          attributes:
+            - name: d2a_val1
+              type: float
+              text: A floating point value for Value 1 of Attribute 2a
+              default: 1.0
+            - name: d2a_val2
+              type: int
+              text: An int for Value 2 of Attribute 2a
+              default: 6
+            - name: d2_a_dict
+              type: dict
+              text: this is a dict
+              default:
+                a: 123
+                b: 567
+                c: 987
+        - name: attribute_2b
+          type: dict
+          text: Attribute 2b is another possible attribute
+          attributes:
+            - name: val1
+              type: str
+              text: Val 1 of D2b
+              default: a_nice_value
+            - name: val2
+              type: str
+              text: Val 2 of D2b
+              default: a_not_so_nice_value
+    - name: attribute_3
+      type: dict
+      text: Attribute 3 has a lot of nesting
+      attributes:
+        - name: attribute_3_1
+          type: dict
+          text: This is a description of Attribute 3.1
+          attributes:
+            - name: attribute_3_1_1
+              type: dict
+              text: This is a description of Attribute 3.1.1
+              attributes:
+                - name: attribute_3_1_1_1
+                  type: dict
+                  text: This is a description of Attribute 3.1.1.1
+                  attributes:
+                    - name: d3111v1
+                      type: str
+                      text: Value 1 of D 3.1.1.1
+                      default: ABC
+                    - name: d3111v2
+                      type: float
+                      text: Value 2 of D 3.1.1.1
+                      required: False
+        - name: attribute_3_2
+          type: dict
+          text: This is a description of Attribute 3.2
+          attributes:
+            - name: d322
+              type: list
+              text: Attribute 3.2.2 has a list of possible subattributes
+              attributes:
+                - name: d322a
+                  type: dict
+                  text: D 3.2.2a executes a series of flips
+                  attributes:
+                    - name: nflips
+                      type: int
+                      text: Number of flips
+                      default: 0
+                    - name: flipaxis
+                      type: str
+                      text: Axis around which flip is performed
+                      choices: ['x','y','z']
+                - name: d322b
+                  type: dict
+                  text: Subattribute D 3.2.2b saves the result
+                  attributes:
+                    - name: filename
+                      type: str
+                      text: name of file to save
+                      default: flipfile.dat
+
+
+The base config must open with the single identifier ``attributes``, under which is a list of one or more top-level attributes.  Every attribute must have a declared type, and attributes can be nested.
+
+``type`` can be one of ``int``, ``float``, ``str``, ``bool``, ``tuple``, ``list``, or ``dict``.  The data content in an attribute is of type ``type`` unless two conditions are met:
+
+1. ``type`` is either ``list`` or ``dict``; and
+2. the keyword ``attributes`` is present.
+
+In this case, there are subattributes.  If the ``type`` was ``dict``, then the subattributes are children of the parent attribute and all operate at the same level.  If the ``type`` was ``list``, then the subattributes defined are expected to be ordered as a list of tasks that the parent attribute executes in the order they appear in the user's config file.  In the base file, both are entered as lists of attributes.
+
+``text`` is just meant for helpful text describing the attribute, and it can be completely free-form as long as it is on one line or blocked multiline using ``|``.
+
+There are several other keys an attribute may have:
+
+1. ``default``: the default value (or values) assigned to the attribute when the user declares it but provides no value.
+2. ``required``: a boolean.  If ``True``, the attribute must be declared (and if it is nested, all its antecedent attributes must be declared too).  If ``False``, no defaults are assigned: the user need not declare the attribute at all, but declaring it without providing a value is an error.
+3. ``choices``: a list of allowed values; if the user gives a value that is not in the list, an error occurs.  This is currently enforced for ``str`` attributes only, and the comparison honors ``case_sensitive`` (below); on an attribute of any other type the list has no effect.  The allowed values appear in interactive help and in the output of ``yclept make-doc``.
+4. ``case_sensitive``: for ``str`` attributes only; a boolean that defaults to ``True``.  When ``False``, the user's value is matched against ``choices`` case-insensitively and stored in casefolded (lower-case) form.
+5. ``docs``: a block that enriches the output of ``yclept make-doc``.  It may contain ``title`` and ``text`` strings and a YAML-format ``example`` showing the attribute in use.  See :ref:`base_config_docs_key` below.
+6. ``value_attributes``: for ``dict`` and ``list`` attributes; declares the schema every *element* must satisfy --- every value of a mapping whose keys the user invents, or every item of a list.  See :ref:`base_config_free_keys` and :ref:`base_config_record_lists` below.
+7. ``value_type``: the same idea for elements that are plain scalars rather than attribute blocks; one of ``str``, ``int``, ``float`` or ``bool``.
+8. ``key_text``: a one-line description of what a free-form key *means*, used alongside ``value_attributes`` or ``value_type`` on a ``dict``.
+9. ``list_defaults``: for ``list`` attributes only; either ``append`` (the default) or ``replace``, controlling what happens to a declared ``default`` when the user supplies a list of their own.  See :ref:`base_config_list_defaults` below.
+
+.. warning::
+
+   A base config is data, and ycleptic reads only the keys listed above.  Any
+   other key is discarded without comment, so a misspelling leaves you with a
+   declaration that does nothing --- writing ``options:`` instead of
+   ``choices:`` yields an attribute that looks constrained but accepts any
+   value.  The same is true of the type names: ``type: string`` is not
+   ``type: str``, and an attribute with an unrecognized type is left entirely
+   unvalidated, its ``choices`` unenforced and its ``default`` never applied.
+
+   Constructing a :class:`~ycleptic.yclept.Yclept` reports these as a
+   :class:`~ycleptic.errors.YclepticSpecWarning`, and ``yclept check-spec``
+   reports them from the command line.  See :ref:`usage_yclept_check_spec`.
+
+.. _base_config_free_keys:
+
+Mappings whose keys the user chooses
+--------------------------------------
+
+``attributes`` names the keys a user may write, and any other key is an error.
+That is the right model for most configuration, but some sections are keyed by
+names only the user knows --- molecules in a formulation, named reactions,
+labelled species.  Declaring such a section as a bare ``type: dict`` passes it
+through unvalidated, which means no defaults, no type checking and no generated
+documentation for exactly the content users are most likely to get wrong.
+
+A ``dict`` attribute may instead declare ``value_attributes``: the schema that
+*every value* under it must satisfy.  The keys stay free.
+
+.. code-block:: yaml
+
+    - name: constituents
+      type: dict
+      text: Molecular constituents of the system
+      key_text: a molecule name, e.g. STY, BPA, GMA
+      value_attributes:
+        - name: smiles
+          type: str
+          required: True
+          text: SMILES string for this molecule
+        - name: count
+          type: int
+          default: 100
+          text: how many molecules to place
+
+A user then writes whatever keys they like, and each value is validated as an
+ordinary attribute block:
+
+.. code-block:: yaml
+
+    constituents:
+      STY:
+        smiles: "C=Cc1ccccc1"
+      GMA:
+        smiles: "CC(=C)C(=O)OCC1CO1"
+        count: 50
+
+``STY`` gets ``count: 100`` from the default; ``GMA`` keeps its 50.  A
+misspelled attribute *inside* a value is still an error, and the message names
+the entry it came from --- ``Attribute 'smiels' invalid; expecting one of
+['smiles', 'count'] under 'constituents[STY]'``.
+
+``value_attributes`` holds ordinary attribute specifications, so anything you
+can write under ``attributes`` you can write here, nesting included.
+
+.. note::
+
+   ``attributes`` and ``value_attributes`` are mutually exclusive on one
+   attribute: a node either names its legal keys or accepts any key, never
+   both.  Declaring both is an error.
+
+``key_text`` is optional but worth writing.  For an ordinary attribute, a user
+learns what to type by reading the list of legal keys; for a free-key mapping
+there is no such list, so ``key_text`` is the only thing telling them what a key
+*is*.  It is rendered by both ``yclept make-doc`` and interactive help.
+
+Values that are plain scalars
+++++++++++++++++++++++++++++++
+
+``value_attributes`` describes a value that is an attribute *block*.  When the
+values are bare scalars --- an atom label mapped to an atom name, a slot number
+mapped to a reactant --- declare ``value_type`` instead:
+
+.. code-block:: yaml
+
+    - name: reactive_atoms
+      type: dict
+      text: Reactive atoms, keyed by label
+      key_text: an atom label such as C1
+      value_type: str
+
+Every value is then checked against that type.  Note that ``value_type: str``
+*is* enforced, unlike a declared ``type: str`` attribute, which ycleptic
+validates through ``choices`` rather than by type; an element schema has no
+such fallback, so an unchecked ``str`` would accept anything.
+
+.. _base_config_record_lists:
+
+Lists of records that all look alike
+--------------------------------------
+
+A ``list`` attribute with ``attributes`` means something specific in ycleptic:
+each item is a single-key mapping naming *which* of the declared attributes it
+is, and the list is an ordered sequence of such tasks.
+
+.. code-block:: yaml
+
+    tasks:
+      - md:
+          ps: 100
+      - minimize:
+          steps: 500
+
+That idiom does not fit a list whose items are flat, multi-key records that all
+have the same shape:
+
+.. code-block:: yaml
+
+    stages:
+      - ensemble: npt
+        temperature: 300
+        ps: 100
+      - ensemble: nvt
+
+For that, declare ``value_attributes`` on the list.  It is the same key used for
+free-key mappings and means the same thing --- *every element satisfies this
+schema* --- with a list's elements being its items:
+
+.. code-block:: yaml
+
+    - name: stages
+      type: list
+      text: The equilibration stages, in order
+      value_attributes:
+        - name: ensemble
+          type: str
+          required: True
+          choices: [min, nvt, npt]
+          text: which ensemble this stage runs in
+        - name: temperature
+          type: float
+          default: 300.0
+          text: temperature in K
+        - name: ps
+          type: int
+          default: 100
+          text: duration in ps
+
+Each item is validated as an ordinary attribute block, so defaults are filled in
+per item and errors name the item they came from --- ``Attribute 'ensemlbe'
+invalid; expecting one of ['ensemble', 'temperature', 'ps'] under 'stages[1]'``.
+
+``value_type`` works on a list too, for a list of plain scalars whose type you
+want checked:
+
+.. code-block:: yaml
+
+    - name: temperatures
+      type: list
+      value_type: float
+      text: the temperatures to sample
+
+.. note::
+
+   ``attributes``, ``value_attributes`` and ``value_type`` are mutually
+   exclusive: a node describes what is under it exactly one way.  Choosing
+   between the first two on a list is a question of shape --- tagged tasks that
+   may differ from one another, or homogeneous records that do not.
+
+.. _base_config_list_defaults:
+
+What a ``default`` list does when the user supplies one
+---------------------------------------------------------
+
+When a ``list`` attribute has a ``default`` and the user also supplies a list,
+ycleptic's historical behavior is to **add** the two: the default comes first,
+then the user's entries.  That is what you want for a list the user extends ---
+a set of standard force-field files, say, to which a user adds one of their own.
+
+It is emphatically *not* what you want for a list the user is meant to
+*supersede*.  A default equilibration ladder of ``[min, nvt, npt]`` and a user
+who writes ``[nvt]`` produces ``[min, nvt, npt, nvt]``: the whole default
+protocol runs, and then the user's step runs again at the end.  Nothing raises;
+the run simply does the wrong thing.
+
+Declare which you mean with ``list_defaults``:
+
+.. code-block:: yaml
+
+    - name: equilibration
+      type: list
+      list_defaults: replace
+      text: the equilibration ladder
+      default: [min, nvt, npt]
+
+``append`` is the default and preserves the historical behavior, so existing
+base configs are unaffected.  Under ``replace``, a list the user supplies is
+used verbatim, and the declared default applies only when the user omits the
+attribute altogether.
+
+Both settings are stated in generated documentation and in interactive help
+wherever a list default is shown, so a user need not guess which applies.
+
+.. warning::
+
+   ``list_defaults`` governs the ``list`` attribute it is declared on.  It does
+   not reach inside a bare ``dict`` attribute, where list-valued entries are
+   merged by :func:`~ycleptic.dictthings.special_update` and are always
+   appended.
+
+.. _base_config_docs_key:
+
+Enriching generated documentation with ``docs``
+-------------------------------------------------
+
+The ``text`` key gives every attribute a one-line description that appears in
+interactive help and generated documentation.  When you want richer, prose
+documentation for an attribute — the kind you would write into a reference
+manual — add a ``docs`` block.  It is used only by ``yclept make-doc`` and is
+ignored during configuration validation:
+
+.. code-block:: yaml
+
+  - name: integrator
+    type: str
+    text: Integration scheme to use
+    choices: [verlet, langevin]
+    default: verlet
+    docs:
+      title: Integration scheme
+      text: |
+        Selects the time-integration algorithm.  ``verlet`` is symplectic and
+        conserves energy well; ``langevin`` couples the system to a heat bath
+        and is appropriate for constant-temperature runs.
+      example:
+        integrator: langevin
+
+``title`` and ``text`` supply a heading and prose for the attribute's generated
+page, and ``example`` is rendered as a YAML code block showing the attribute in
+use.  See :ref:`usage_yclept_makedoc` for how the tree is generated.