Document the body frame as KiteUtils' KA and drop the KB definition

[1-Bort-1]

TL;DR

The docs now state that VortexStepMethod's body frame is KiteUtils' KA frame (x LE→TE, y to the right tip, z = x × y up), and the separate KB definition is gone. KB defined z as Y × X, which points down, while the solver has always had z up and lift along +z.

What was checked

On a flat rectangular wing, the panel axes come out as x_airf = [1,0,0], y_airf = [0,1,0] and z_airf = [0,0,1], with determinant +1. At α = 5° the solve gives Fz = +2384 N, and the geometry puts its first section at +y. In the code, z is built as x × span (panel_axes) and lift as va × spanwise. So the frame is right-handed, and KB was KA with a typo in its z line. The old sentence "seen from the front, the front left is positive" names the same +y as KA's "towards the right tip", and the page now uses both wordings. The existing Panel Reference Frame and the frame closes as z = x cross y testsets already pin this, so there is no new test.

What changed

• reference_frames.md: the KB section is replaced by a KA section that links KiteUtils. The line "different from the kite reference frame K used in KiteModels/KiteUtils" is removed, and turn rates, va_vec, forces and coefficients are stated in KA.
• The README, the index page, the glossary, and the Panel, BodyAerodynamics, reinit!, solve!, solve, VSMSolution and calculate_results docstrings say KA where they said KB or "kite body frame".
• The old "drag along +X, lift along +Z" sentence and "CL, CD, CS are defined in the KA frame" were only true at α = β = 0. cl/cd/cs are taken along the apparent wind (prescribed_va_directions: lift = va × span), while cfx/cfy/cfz are the body-axis components. The page now says so, and the CAD frame's Y axis uses the same "right tip" wording as KA.

As agreed on the thread (option A), there is no KiteUtils dependency here. Nothing in src/ or ext/ converts between body and world frames yet, so the dependency and the first fromENU2NED call come with turbulent inflow (#34). The keyword kite_body_origin keeps its name because it is API.

Verification

• Reproduced first: flat-wing probe gives z_airf = [0,0,1], det = +1, Fz = +2384 N. The docs' Y × X gives −z.
• test/panel/test_panel.jl: 26/26 and 8/8 pass after rebasing onto v6.0.0 (juliaserver), on 597ac27. This is a docs-only change, so there is no red-before test.
• Docs build clean after the review fixes (554234d). The only warnings are the existing HTML size warnings on functions.md and private_functions.md.
• Local CI mirror (agent ci-local, Julia 1.13, full Pkg.test()): PASS in 5 min, exit 0, on 597ac27; 554234d changes only prose and docstrings and was not re-run through it. GitHub CI on 554234d: Julia 1.12 and 1.13 on ubuntu, 1.12 on windows, setup test and Documentation PASS; macOS 1.12 was still queued when this card was written.
• REUSE lint: n/a, the repo has no bin/reuse_lint.
• Risk: none in code. The only lines outside docs are docstrings.

Scope

+39 / −26 across 8 files, all prose. It is a one-for-one swap of KB for KA, a rewritten frame section that separates body-axis from wind-axis coefficients, and a changelog entry under a new Unreleased section, because main released v6.0.0 while this branch was open.

Closes #383 · task VortexStepMethod.jl-383

[1-Bort-1]

Independent review (advisory)

Verdict: APPROVE WITH COMMENTS · 1 inline, 0 off the diff

Good

• The docs-only scope matches the card's option A: I checked every hunk, and each is prose or a docstring, with no KiteUtils dependency or src logic change.
• The new KA definition in reference_frames.md, z = x × y, is right-handed and gives z up. That matches the card's probe and the claim that z is built as x × span.
• The countermand "different from the kite reference frame K" is deleted rather than reworded, as §7 asks.
• kite_body_origin keeps its name, as §3 requires for a keyword argument, and the card says why.
• The three touched docstring lines are rewrapped under 92 columns. I checked each hunk.
• The CHANGELOG entry is compact, sits under a new Unreleased section, and says the solver's frame is unchanged.

Not good

• docs/src/reference_frames.md:25 — "Drag is along +X, side force along +Y and lift along +Z" holds only when α = β = 0. Drag follows the apparent wind and lift is perpendicular to it, so readers will take body-axis force components for CD and CL. Say the body-axis force components are Fx, Fy, Fz, or delete the line.
• The KB-to-KA swap stops short of the files it opens. src/body_aerodynamics.jl still says "kite body frame" or "kite body reference frame" at lines 10, 29, 68, 70 and 306, next to the line 801 that was changed. Found by grep.
• docs/src/glossary.md:18 still says "kite body x-axis". It is one step out, but it is the same noun this PR renames.
• reference_frames.md line 36 says CL, CD and CS are "defined in the KA frame". CL and CD are wind-axis coefficients, so this pre-existing line now sits next to an explicit axis claim and reads as more authoritative. It is worth one sentence while the file is open.
• The CAD section's Y bullet uses the old "front left is positive" wording, and the KA section uses "right tip". Two phrasings for the same axis in the same file invite a reader to wonder whether they differ.

_{claude, rubric CLEAN_CODE.md. A different lab from the implementer
on purpose: a reviewer sharing its blind spots would not flag its mistakes.}

[1-Bort-1]

MINOR: "Drag is along +X, side force along +Y and lift along +Z" holds only when α = β = 0. Drag follows the apparent wind and lift is perpendicular to it, so readers will take body-axis force components for CD and CL. Say the body-axis force components are Fx, Fy, Fz, or delete the line.

[1-Bort-1]

Fixed in 554234d. The line now names the body-axis components Fx, Fy, Fz (cfx, cfy, cfz), and the output list says that CL, CD and CS are wind-axis coefficients that match them only at α = β = 0. The same commit also handles the other findings: the body_aerodynamics.jl docstrings and the glossary say KA, and the CAD Y bullet uses the 'right tip' wording.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[1-Bort-1]

Local full suite: PASS (7 min, Julia 1.13.0, one cell of the matrix)