[lmoresi]

What changed: a new capability guide docs/developer/guides/fault-multigrid.md (kind: guide, families Stokes and Stokes_Constrained), a row in the developer index's capability-guide table and the toctree, and **Status:** lines on the two design documents it draws on (fault-patch-multigrid-2026-08.md, fault-parallel-placement-2026-09.md). Documentation only; no code.

Why: the fault-multigrid rulings (the base is never cut or rebalanced; one hierarchy carries the fault as the model has it; the placed ribbon serves both realisations) kept being re-derived in new sessions, and the only place they were written down was the wiki. The guide states them once, says what ships on development (the fault-patch design: the Galerkin ladder plus the strong patch keyed on the fault physics, the iteration counts to expect, the configuration rules learned from failures, the width ruling), where parallel imbalance comes from, and names the split-level hierarchy measured on feature/fault-split-multigrid as pending rather than available. Every API name was checked against development; the docs build renders the page with no new warnings. The provenance is the journal topic page it links.

Checklist (UW3 Style Charter — docs/developer/UW3_STYLE_CHARTER.md)

• I have read the Style Charter and followed it over the surrounding code (S2)
• No drive-by refactors, renames, or "while I was here" cleanups (S9)
• Bug fixes ship the regression test, written first, with level_* and tier_* markers (S8): not a bug fix
• No hedging names (maybe_ / try_ / do_) and no commented-out code (S3, S4)
• Every exception swallow states its sanctioned failure mode in a comment (S4): no code
• New data access uses .array / mesh.X.coords — no with ....access(...), no mesh.data (S7): no code
• Parallel safety considered — np2/np4 checked where swarm/mesh/solver dispatch is touched (S11): no code
• No pixi.toml / pixi.lock or other dependency changes riding in an unrelated PR
• AI-assisted work carries the attribution line below

Underworld development team with AI support from Claude Code

---

Generated by Claude Code

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

[lmoresi]

Updated 2026-11-01 after Louis's ruling on #892 (issuecomment-6550186134) and the merges of #889, #890, #912 and #915.

• development merged in (8d9d596); the index-table conflict with The add-on partitioned once, custom multigrid on empty ranks, and the rotated solve's switch and record #890 keeps both guide rows, and guides/faults-in-convection is added to the developer toctree it was missing from.
• fault-multigrid.md (772dfa6): the "what production runs" paragraph now states the ruled tail, the welded base with the split S level on top and the FAC LU patch on that finest level, with the counts from the tail sweep on #892: FAC patch blocks run the configured LU on the rotated route #912's build; the chain of split ladders is named as the measured alternative, not production. The configuration rule on the blocks says FAC blocks are LU and records the ILU(0) period on the rotated path (2026-09-03 to #892: FAC patch blocks run the configured LU on the rotated route #912). The split-level section says the library merged and what the pre-#892: FAC patch blocks run the configured LU on the rotated route #912 measurements were made on. Mesh.multigrid_levels replaces the private accessor.
• faults-in-convection.md (same commit): the hierarchy section, code and table rewritten to the welded tail; the chain kept as the labelled alternative with the reason the earlier table misled; the ILU-era table retired to the journal.

Sphinx builds clean on the branch (exit 0, no warnings on the changed pages). Journal: the decision and finding entries of 2026-11-01 on the fault-multigrid topic.

---

Generated by Claude Code

[lmoresi]

Correction pushed (see the latest commit): kaiju's budget of the np 16 annulus pair (#892, issuecomment-6552218825) supersedes the comment I cited yesterday. The welded arm carried a 3584-row patch on one rank and the chain none, the velocity work is equal (8.65 against 8.74 F-cycles per solve) and the times are a wash; the patch's serial LU costs 5 to 6 % of the solve. Both guides now say that, and the parallel section carries the measured cost and the block rule (one structural block per rank, no row cap; the 2000-row cap is for zone blocks). Sphinx still builds clean.

---

Generated by Claude Code