Document the two size-grid quadrature schemes

[gustavdelius]

Follow-up to #476. Based on that branch, so this PR's diff shows only the documentation; GitHub will retarget it to master once #476 merges.

Why

second_order_w was documented in vignette("fft") from the kernel's side, but nothing said where each bin integral is performed across the model as a whole. That gap is what let #474 through: the prey-bin quadrature is folded into the predation kernel at setup, so a summary function that bin-averages its prey weight as well applies it twice — and because the resulting (1 + beta) / 2 factor is uniform, it cancels in any proportion and nothing complains.

vignettes/numerical_details.qmd

"Applying each bin integral exactly once", a new subsection inside the existing Point values and bin averages. Derives the encounter kernel weight, explains why the w_p dw_p in the run-time sum is a normalisation the kernel has already divided out rather than a first-order quadrature weight left on the table, and tabulates which factor of each of mizer's integrals is bin-integrated and in which setter. Ends with the two corollaries — never average N or dw, and a decomposition borrows its parent rate's quadrature — and the note that getPredKernel() is not the kernel the convolution uses once the flag is on.

"The second_order_w switch", a new section. The two independent entries and why they are independent; a full FALSE vs TRUE table including the rows that stay point values (the growth-type rates, and getN()); and a recipe for making your own diagnostic second-order accurate, split into the plain-integral case and the built-from-rates case. It closes with the identity check and how to read off (1 + beta) / 2 versus 2 / (1 + beta) when it fails.

Also drops a paragraph that had been duplicated verbatim in the existing section.

All code snippets were run and produce the stated output; the vignette renders with all cross-references resolving.

.claude/skills/size-grid-integrals.md

The same material as a decision procedure, in the style of the existing skills: the rule, four cases (plain integral / derived from rates / inside the convolution / new rate setter), the traps, the verification steps, and a helper table. Two things in it go beyond what #474 needed:

• Growth-type rates are never bin-averaged. The natural over-correction after reading about this bug is to start averaging everything; g, e, encounter and feeding level are point values under both schemes.
• Testing only the default path proves nothing. Both getDiet(proportion = FALSE) overcounts by (1+beta)/2 when second_order_w bin averaging is on #474 bugs were invisible with the flag off.

It defers the theory to the vignette rather than duplicating it, the way species-param-defaults.md defers its table to default_parameters.qmd.

AGENTS.md

An architectural note that the model has two discretisations and that the default hides the second, plus a pointer to the skill. This is the part that would have prevented the bug: reading getDiet() gave no hint the flag existed.

🤖 Generated with Claude Code