[docs] describe corrected FDFD solver and modal conventions

docs/api/fdfd.md

@@ -33,6 +33,28 @@ the requested output shape. Both transforms center their origins at index
 `size // 2`; padding and cropping preserve that sample. The inverse does not
 modify input spectra.
 
+Transforms use the library's `exp(+i omega t)` time convention: outgoing plane
+waves vary as `exp(-i k dot r)`, so the angular projection uses a positive
+Fourier phase. The inverse uses a negative phase. Far-field vector pairs are
+ordered as polar and azimuthal components; near-field pairs are Cartesian.
+
+## Solver and port calibration
+
+The default QMR wrapper raises `RuntimeError` on breakdown or failure to
+converge. PEC rows impose zero electric fields with unit diagonal entries;
+`solvers.generic` zeroes the corresponding source and initial-guess entries.
+H-only and EH operators impose analogous constraints for PMC locations.
+
+FDFD port calibration uses the complete incoming-amplitude matrix from all
+excitations, solving `S @ incoming_amplitudes = raw_outgoing_amplitudes`.
+Diagnostics include these matrices and the incoming/outgoing flux Gram
+matrices. Guided powers retain cross terms between nonorthogonal modes.
+
+Lossless modes at or above the propagation-grid band edge require a finer
+mesh for power normalization. Lorentz-normalized evanescent modes use the
+decaying spatial branch. Expansion on graded grids uses each electric
+component's own Yee intervals.
+
 ## SCPML conventions
 
 `stretch_with_scpml` now uses `-1` for the low-index face and `+1` for the