Add parallel flow to x2 in KIM-FP

[marjohma]

Summary

• add toroidal-flow profile input and configuration plumbing
• include the parallel-flow contribution in the FP susceptibility argument x2
• verify zero-flow compatibility, sign behavior, interpolation, and periodic-background handling

Why

The FP response now represents the configured plasma flow instead of silently omitting its parallel component.

Validation

Validated cumulatively at the stack head:

• cmake --build build -j2
• ctest --test-dir build -E 'test_rhs_balance|test_periodic_convergence|test_periodic_vs_global' --output-on-failure — 35/35 passed

Known red gates are intentionally excluded from that command: the pre-existing test_rhs_balance baseline failure, the periodization-deformation acceptance gate, and the unresolved periodic-vs-global 5% agreement gate.

Stack

Base: fix/kim-fp-02-multispecies-background
Head: fix/kim-fp-37-parallel-flow

Closes #37

[marjohma]

Review (standards + spec vs #37). Core implementation verified correct — the x2 Doppler term matches the issue formula exactly (a dedicated test fails on wrong sign or dropped term), zero flow is asserted bitwise equivalent, the toroidal→parallel convention is documented with the Vz/h_z projection applied exactly once, and the E_r/x2 usage is a documented perp/parallel decomposition, not double counting. Negative fixtures cover both rejection reasons; non-goals respected. Marking ready. Findings for follow-up:

Spec gaps (test quality)

1. The periodized-flow fixture uses a constant Vpar = 2.5e6 — "flow is unchanged in the as-is interval and periodic through the seam" is near-vacuous for a constant profile (any periodization returns the constant). A radially varying flow would make the as-is-preservation and seam checks meaningful. The fixture does still catch a dropped/zeroed flow in the periodic path.
2. Spec asked to "pass the already-read Vz profile into plasma state"; the implementation re-reads Vz.dat from disk with its own interpolation (profile_input_m.f90:458 via species_mod.f90:1310) instead of reusing the profile read for E_r. Behaviorally equivalent, but two readers of the same file can drift.
3. The error stop wiring in read_from_text (species_mod.f90:1319) is never exercised — the validator is tested directly.

Compatibility (deliberate, but release-note-worthy)

• Two-way behavior change: existing run dirs with a finite Vz.dat and an old config (no parallel_flow_convention key, default 'none') now hard-fail at startup; conversely the shipped example nmls set 'toroidal', silently opting copied configs with a finite Vz.dat into new physics (ion Maxwellian drift in x2).

Docs / config polish

• parallel_flow_convention is added to both nmls without a ! doc comment and under the "Output profile filenames" header where it doesn't belong.
• AGENTS.md "Required Profile Files" still describes Vz.dat as plain optional — now inaccurate on both the fatal-error condition and the FP-susceptibility consumption.
• The x2 hunk bundles a silent latent-bug fix (plasma% → plasma_in% for omega_c) not mentioned in the commit message (verified: no numeric effect for current callers).

Pre-existing oddity (not this PR's fault): in x2_cc, the new Doppler term uses cell-centered 0.5*(kp(j)+kp(j+1)) while the existing base term uses nodal omega_c(j) — mixed centering within one expression.