docs: strip design narrative from module docstrings, keep API contract

13 files changed, 11 insertions, 80 deletions

diff --git a/edify/builder/builder.py b/edify/builder/builder.py
index 40f103e..0e775f1 100644
--- a/edify/builder/builder.py
+++ b/edify/builder/builder.py
@@ -1,14 +1,4 @@
-"""The composition root for :class:`RegexBuilder` — the fluent regex-builder class.
-
-The class itself defines no chain methods; every method comes from one of
-the mixins under :mod:`edify.builder.mixins`. The composition order does
-not matter for behavior because the mixins do not override each other's
-methods, but they are listed alphabetically by mixin name for predictability.
-
-The immutable-state plumbing (``_state`` attribute + ``_with_state`` helper)
-lives on :class:`edify.builder.core.BuilderCore`, which every fluent surface
-in the package inherits from.
-"""
+"""The composition root for :class:`RegexBuilder` — the fluent regex-builder class."""
 
 from __future__ import annotations
 
diff --git a/edify/builder/mixins/flags.py b/edify/builder/mixins/flags.py
index a4443ee..c46c29e 100644
--- a/edify/builder/mixins/flags.py
+++ b/edify/builder/mixins/flags.py
@@ -2,8 +2,7 @@
 
 Each method returns a new builder whose flags snapshot has the corresponding
 field enabled. Flags are pattern-global — position in the chain does not
-matter — so the methods read identically whether placed at the start, the
-end, or anywhere in between.
+matter.
 """
 
 from __future__ import annotations
diff --git a/edify/builder/mixins/operators.py b/edify/builder/mixins/operators.py
index eb3baba..a5b8fa7 100644
--- a/edify/builder/mixins/operators.py
+++ b/edify/builder/mixins/operators.py
@@ -1,16 +1,9 @@
 """The :class:`OperatorsMixin` — ``+`` concatenation and ``|`` alternation.
 
-Both operators produce a new instance of the same concrete fluent surface
-(a :class:`edify.builder.builder.RegexBuilder` or a
-:class:`edify.pattern.composition.Pattern`), leaving both operands untouched
-per the immutable-builder contract.
-
-Semantically:
-
-* ``a + b`` embeds ``b`` at the end of ``a`` — the algebra equivalent of
+* ``a + b`` embeds ``b`` at the end of ``a`` — equivalent to
   ``a.subexpression(b)``.
 * ``a | b`` produces a fresh instance whose sole element is an
-  ``AnyOfElement`` containing ``a`` and ``b`` — the algebra equivalent of
+  ``AnyOfElement`` containing ``a`` and ``b`` — equivalent to
   ``fresh.any_of().subexpression(a).subexpression(b).end()``.
 """
 
diff --git a/edify/compile/escape.py b/edify/compile/escape.py
index c82a345..b78454c 100644
--- a/edify/compile/escape.py
+++ b/edify/compile/escape.py
@@ -1,8 +1,4 @@
-"""Escape user-provided string fragments for safe insertion into a regex pattern.
-
-Single-purpose wrapper around :func:`re.escape` so the builder never embeds
-user input directly into a compiled pattern.
-"""
+"""Escape user-provided string fragments for safe insertion into a regex pattern."""
 
 from __future__ import annotations
 
diff --git a/edify/compile/leaves.py b/edify/compile/leaves.py
index ed60f5b..3e705ac 100644
--- a/edify/compile/leaves.py
+++ b/edify/compile/leaves.py
@@ -1,9 +1,4 @@
-"""Render leaf elements to their regex string.
-
-Every leaf in :mod:`edify.elements.types.leaves` maps to a fixed string that
-never depends on children or quantifier state, so the renderer is a single
-``match`` over the leaf union.
-"""
+"""Render leaf elements to their regex string."""
 
 from __future__ import annotations
 
diff --git a/edify/elements/types/base.py b/edify/elements/types/base.py
index 9896740..2e7265e 100644
--- a/edify/elements/types/base.py
+++ b/edify/elements/types/base.py
@@ -1,15 +1,9 @@
 """Base class shared by every concrete element in the edify AST.
 
-Provides a common type that recursive children can reference
-(``tuple[BaseElement, ...]`` for capture children, ``BaseElement`` for the
-quantifier's single child) without forcing each module to import the full
-:data:`edify.elements.types.Element` union — which would form an import
-cycle since the union lists every concrete subclass.
-
-Function signatures that consume or return AST nodes should still use the
-precise :data:`Element` union from :mod:`edify.elements.types`; this base
-exists only so that the dataclass field annotations type-check without a
-circular import.
+Provides a common type that recursive dataclass fields can reference —
+``tuple[BaseElement, ...]`` for capture children, ``BaseElement`` for the
+quantifier's single child. Function signatures that consume or return AST
+nodes should use the precise :data:`edify.elements.types.Element` union.
 """
 
 from __future__ import annotations
diff --git a/edify/elements/types/captures.py b/edify/elements/types/captures.py
index 1f585fa..128d339 100644
--- a/edify/elements/types/captures.py
+++ b/edify/elements/types/captures.py
@@ -9,10 +9,6 @@ capture group already matched, addressed by index (``\\1``) or by name
 * :class:`NamedCaptureElement` — ``(?P<name>...)`` named capture.
 * :class:`BackReferenceElement` — ``\\<index>`` numbered back-reference.
 * :class:`NamedBackReferenceElement` — ``(?P=name)`` named back-reference.
-
-Recursive ``children`` references use :class:`BaseElement` so the dataclass
-field annotations type-check without importing the full ``Element`` union
-(which would form a cycle).
 """
 
 from __future__ import annotations
diff --git a/edify/elements/types/chars.py b/edify/elements/types/chars.py
index 6f7c491..5545cd9 100644
--- a/edify/elements/types/chars.py
+++ b/edify/elements/types/chars.py
@@ -11,9 +11,6 @@ bounds) and emit the corresponding regex fragment at compile time.
 * :class:`AnythingButCharsElement` — an inline ``[^abc]`` negated class.
 * :class:`AnythingButRangeElement` — a negated ``[^a-z]`` range.
 * :class:`AnythingButStringElement` — a sequence of negated single-character classes.
-
-Every class inherits from :class:`edify.elements.types.base.BaseElement` so
-it participates in the ``Element`` union and in :func:`isinstance` dispatch.
 """
 
 from __future__ import annotations
@@ -38,10 +35,6 @@ class CharElement(BaseElement):
 class StringElement(BaseElement):
     """A multi-character literal string.
 
-    A literal string needs to be wrapped in a non-capturing group when a
-    quantifier is applied to it, hence the dedicated class separate from
-    :class:`CharElement`.
-
     Attributes:
         value: The string to match; already escaped for the compile path.
     """
diff --git a/edify/elements/types/groups.py b/edify/elements/types/groups.py
index 3934b7b..54ecc0f 100644
--- a/edify/elements/types/groups.py
+++ b/edify/elements/types/groups.py
@@ -11,9 +11,6 @@ construct that does not introduce a numbered capture:
 * :class:`AssertNotAheadElement` — ``(?!...)`` negative lookahead.
 * :class:`AssertBehindElement` — ``(?<=...)`` positive lookbehind.
 * :class:`AssertNotBehindElement` — ``(?<!...)`` negative lookbehind.
-
-Recursive ``children`` references use :class:`BaseElement` so the dataclass
-field annotations type-check without importing the full ``Element`` union.
 """
 
 from __future__ import annotations
diff --git a/edify/elements/types/leaves.py b/edify/elements/types/leaves.py
index 5a1a678..d776929 100644
--- a/edify/elements/types/leaves.py
+++ b/edify/elements/types/leaves.py
@@ -4,11 +4,6 @@ Each leaf represents a regex construct that emits a fixed string and carries
 no parameters: ``\\d`` for :class:`DigitElement`, ``\\b`` for
 :class:`WordBoundaryElement`, ``^`` for :class:`StartOfInputElement`, etc.
 
-Every leaf is :func:`dataclasses.dataclass` with ``frozen=True`` so the whole
-AST is immutable; the builder produces new branches by constructing new
-elements rather than mutating existing ones. All leaves inherit from
-:class:`edify.elements.types.base.BaseElement` so they participate in the
-``Element`` union and in :func:`isinstance` dispatch.
 """
 
 from __future__ import annotations
diff --git a/edify/elements/types/quantifiers.py b/edify/elements/types/quantifiers.py
index 41d82c8..9fbd8e4 100644
--- a/edify/elements/types/quantifiers.py
+++ b/edify/elements/types/quantifiers.py
@@ -19,10 +19,6 @@ Lazy variants:
 * :class:`ZeroOrMoreLazyElement` — ``*?``.
 * :class:`OneOrMoreLazyElement` — ``+?``.
 * :class:`BetweenLazyElement` — ``{lower,upper}?``.
-
-The wrapped ``child`` is annotated as :class:`BaseElement` to avoid forming
-a cycle with the full ``Element`` union; the compile path dispatches on the
-concrete child type.
 """
 
 from __future__ import annotations
diff --git a/edify/elements/types/union.py b/edify/elements/types/union.py
index 27aed96..8cf1cb5 100644
--- a/edify/elements/types/union.py
+++ b/edify/elements/types/union.py
@@ -1,11 +1,4 @@
-"""The sealed :data:`Element` union — every concrete element class spelled out.
-
-Function signatures that consume or return AST nodes use this union so the
-type checker enforces that every reachable case is one of the listed
-classes. Internal recursive references inside the dataclass definitions use
-:class:`edify.elements.types.base.BaseElement` to avoid forming an import
-cycle with this module.
-"""
+"""The sealed :data:`Element` union — every concrete element class spelled out."""
 
 from __future__ import annotations
 
diff --git a/edify/pattern/anchors.py b/edify/pattern/anchors.py
index f4fe21b..6fda3de 100644
--- a/edify/pattern/anchors.py
+++ b/edify/pattern/anchors.py
@@ -1,15 +1,9 @@
 """Pre-built :class:`Pattern` instances for the ``^`` and ``$`` anchors.
 
-These constants exist so the operator algebra reads naturally:
-
 .. code-block:: python
 
     from edify import END, START, Pattern
     quad_digit = START + Pattern().exactly(4).digit() + END
-
-They are immutable — the underlying ``BuilderState`` never mutates and the
-operator overloads always return fresh instances — so importers can share
-them freely without worrying about interference between call sites.
 """
 
 from __future__ import annotations