[mmacy]

A developer reading the reference for osrlib.crawl.encounter and osrlib.crawl.battle can now start a fight and run it without opening the source. Each module docstring leads with where the module sits: what it takes from the session, which member is the entry point, which commands drive it, and which events carry its results. start_encounter, end_encounter, and start_battle each say when to call them, which command to use instead and why, and what comes back, with a runnable example. Every model field, module constant, and policy method has its own docstring, so nothing on the two pages renders as a bare name any more. ActionPolicy says how to register a policy of your own and shows one that runs, and BattleState points a caller who wants to change a fight in flight at the referee commands instead.

I corrected two docstrings because the code disagreed with them. BattleState said "the groups live on the encounter state" and nothing about its own fields; the round handler writes all nine, and each now says what it is for (src/osrlib/crawl/battle.py:245). EncounterState's round field is not incremented by every accepted encounter command, as a first draft of mine claimed: a chase counts its rounds on pursuit instead, and EngageBattle adds none (src/osrlib/crawl/encounter.py:243).

Review of the first push found four more claims in the battle module docstring that overstated the code, all now corrected against it. A mirror image figment pops on every incoming attack, hit or miss, and no attack roll is made at all. A concentration spell's effects release when the caster declares anything other than cast, turn_undead, or hold, not on any other action. A protection ward survives the melee that would break it when its effect definition carries an unbreakable param, which nothing in the shipped spell data sets. Casting breaks the caster's invisibility in the kernel's cast_spell rather than in this module, so the docstring now attributes it there.

Three things I rewrote because they named nothing a reader could look up. The battle module docstring said the machine "consumes marker conditions and battle-bound spell effects", a phrase that appears nowhere else in the package; it now names the four cases it stands for, each checked against the code. NPC_PARTY_MORALE said a morale 9 group breaks on a 2d6 of 10 or more "before modifiers", which reads as though the situational modifier were ignored; check_morale adds it before the comparison, so the docstring now says so (src/osrlib/crawl/battle.py:874). MELEE_RANGE_FEET said the party's own groups sit at 5 feet when it turns to fight mid-chase; the groups are the monsters', and the engage handler puts them at the current gap rather than at 5, so the sentence now describes the case that does land at 5, a pursuit that catches the party (src/osrlib/crawl/battle.py:219).

The adaptations register is now defined in a clause and linked wherever either file names it. The link is the full URL rather than the heading anchor, because the page's H1 contains a word the docs vocabulary gate bans inside a docstring and the anchor slug carries it too. end_encounter says what it does with no encounter open, which is to raise AttributeError on its first line, and that it resets session.odometer_thirds (src/osrlib/crawl/encounter.py:980). The code comments in both files are in the same register as the docstrings.

Every example runs under the docs harness. None is marked no-run.

Multi-line Returns descriptions need their continuation lines indented one level deeper than the first, or griffe splits each line into its own table row. The ones in these two files are written that way. Any later batch with a Returns section longer than one line will hit the same thing.

https://claude.ai/code/session_01GL26QnA6dCrvUc3WmhzFSa