Add comprehensive sign conventions reference documentation

[krystophny]

Summary

• New docs/sign_conventions.rst documenting all sign conventions in one place
• Cross-reference from docs/outputs.rst to the new page
• Added to docs/site.rst toctree
• Summary in CLAUDE.md for AI-assisted development

What is documented

• Coordinate system (psi, theta, zeta/phi) definitions and normalization
• Helicity and handedness (ip_direction, bt_direction, helicity = +/-1)
• F = R*Bt forced positive, q NOT forced positive
• Why positive m is always resonant (nn > 0 and q > 0 by convention)
• Spectrum output sign conventions (real-space, SURFMN, VACUUM interfaces)
• Rotation velocity conventions in PENTRC (omega_E, diamagnetic frequencies, total rotation)
• COCOS compatibility note (GPEC does not use COCOS)
• Quick reference table and source code line references

Motivation

These conventions are currently scattered across docs/outputs.rst, dcon/README,
inline code comments, and tribal knowledge. Having a single authoritative reference
reduces user confusion, especially around rotation sign conventions and the
positive-m resonance design choice.

Test plan

• Build Sphinx docs (cd docs && make html) and verify no RST warnings
• Verify cross-references resolve correctly
• Review for physics accuracy

[krystophny]

@logan-nc I let Claude deep-dive into sign conventions. Could you have a look if this is accurate some time and let me know what is wrong?

[logan-nc]

Awsome @krystophny!
@matt-pharr and @ebursch have often struggled with sign and normalization conventions in the code and would be best to review this I think.

Note that we have a new Julia version of GPEC @ https://github.com/OpenFUSIONToolkit/GPEC with documentation at https://openfusiontoolkit.github.io/GPEC/dev/. My hope is that we rewrite things with more consistent / clear conventions - but it would be great to add explicit documentation like this there as well.

[krystophny]

Awsome @krystophny! @matt-pharr and @ebursch have often struggled with sign and normalization conventions in the code and would be best to review this I think.

Note that we have a new Julia version of GPEC @ https://github.com/OpenFUSIONToolkit/GPEC with documentation at https://openfusiontoolkit.github.io/GPEC/dev/. My hope is that we rewrite things with more consistent / clear conventions - but it would be great to add explicit documentation like this there as well.

Thanks for the fast reply, @logan-nc . Good to hear that there is a modernized version. Don't forget that we are working on Julia level of user friendliness in Fortran e.g. on https://github.com/lfortran/lfortran and https://github.com/lazy-fortran/fortplot ;)

[matt-pharr]

Rebasing this onto a native branch so I can push a tweak to it, will reopen a new PR. Thanks for the contribution

[logan-nc]

@krystophny and @matt-pharr I think there may have been and oversight in the q and cocos claims. This claims q is simply read in, but in reality it is calculated from the field line integrations of the Equilibrium module. I don't think I have ever never seen a negative q in GPEC, so believe it is always positive (this documentation says it can be either sign). Since resonant m are always positive, q must be positive.

Note also that users have reported g-files need to be in COCOS=2. I am no expert, but am surprised to see the convention here has somehow escaped all COCOS numbering... are you sure it isn't 2? I admit I didn't have time to check.