[mmacy]

I rewrote every docstring in src/osrlib/core/items.py and src/osrlib/core/treasure.py for someone reading the published reference who has never opened the source. A reader can now find out which member to call for equipment, inventories, magic items, encumbrance, and treasure generation, what to hand it, what comes back, and what to do with that, without leaving the page. Every pydantic field and every enum member carries its own attribute docstring, so nothing in either module renders as a bare name. Id-typed parameters link the loader in osrlib.data and the generated content-id index that lists valid values, and the duck-typed parameters (character on sword_control_check, allocator on the generation functions) name the classes that satisfy them and link them, with no annotation changed. The entry points carry runnable examples, and every example in both files runs under the docs examples harness.

Five docstrings were wrong about the code and are now corrected. generate_treasure (src/osrlib/core/treasure.py) promised a ValueError for an unknown tier, but the tier is only read once the roll reaches a magic item, so a hoard of coins alone accepts any string; generate_treasure_entries and generate_unguarded_treasure now carry the same note, which neither had before. equipment_weight_coins (src/osrlib/core/items.py) said ammunition weighs nothing, when the code weighs an ammunition template like any other and it is the four shipped templates that are weight 0; it now says so. treasure_weight_coins now says a stack weighs its template's figure times its quantity, with a spent stack counting as one. unequip now says the curse check runs before the slot search, so an item under a revealed curse reports the curse whether or not it is equipped. The EquipmentCatalog.get example printed Torch where the shipped display name is Torches (6), which is fixed, and the gear and ammunition name fields now say that the price list names the lot. I also dropped the count of weapons from the items module docstring, since prose counts drift as a surface grows.

No example is marked no-run. The only members without a docstring are the pydantic validators and the other underscore-prefixed helpers, which the reference hides. One thing for you to decide rather than me: the tier check is not a pure pre-check in the three generation entry points, so tier="bogus" silently produces a coins-only hoard. I documented the behavior and did not change it.

https://claude.ai/code/session_01GL26QnA6dCrvUc3WmhzFSa