[LOW] DOC: Add NAV canonical sequences, anti-patterns, and troubleshooting guide

[fermga]

Problem

While Transition docstring is comprehensive, it lacks:

• Explicit canonical sequences from TNFR.pdf
• Anti-patterns (what NOT to do)
• Troubleshooting guide for failed transitions

Proposed Documentation

Add to docs/source/operators/NAV_GUIDE.md:

Canonical Sequences

Sequence	Purpose	Status
SHA → NAV → AL	Reactivation from latency	Requires #2861
IL → NAV → OZ	Stable to exploration	Supported
AL → NAV → IL	Activation to stabilization	Supported
NAV → ZHIR	Enable mutation	Requires U4b check
THOL → NAV → RA	Emergence to propagation	Supported

Anti-Patterns

• ❌ NAV → NAV (redundant, no intermediate stabilization)
• ❌ OZ → NAV (high ΔNFR makes transition chaotic - use IL first)
• ❌ NAV from deep latency (EPI < 0.05) without AL
• ❌ NAV → SHA immediately (contradictory - why transition then pause?)

Troubleshooting

"OperatorPreconditionError: νf too low"
→ Apply AL (Emission) or wait for ΔNFR to increase νf

"NAV applied but node behavior unchanged"
→ Likely missing Issue #2861 implementation - NAV not transforming structure

"EPI drifts significantly after NAV"
→ Check ΔNFR before NAV - should be < 1.0 for stable transition

"NAV from SHA doesn't clear latency"
→ Requires Issue #2861 implementation of _handle_latency_transition

"Phase θ unchanged after NAV"
→ Requires Issue #2861 implementation of _apply_structural_transition

Usage Examples

Example 1: Reactivation from Silence

from tnfr.structural import create_nfr, run_sequence
from tnfr.operators.definitions import Silence, Transition, Emission

# Node enters latency
G, node = create_nfr("sleeping", epi=0.3, vf=1.0)
run_sequence(G, node, [Silence()])  # SHA: vf → 0, latent=True

# Reactivation via NAV
run_sequence(G, node, [Transition(), Emission()])  # NAV clears latency, AL activates
assert not G.nodes[node].get("latent", False)
assert G.nodes[node]["vf"] > 0.1

Example 2: Stable to Exploratory Transition

from tnfr.operators.definitions import Coherence, Transition, Dissonance

# Stabilized node
G, node = create_nfr("stable", epi=0.6, vf=1.0)
run_sequence(G, node, [Coherence()])  # IL: ΔNFR reduced

# Transition to exploration
run_sequence(G, node, [Transition(), Dissonance()])  # NAV → OZ safe

Example 3: Emergence to Propagation

from tnfr.operators.definitions import SelfOrganization, Transition, Resonance

# Self-organized node
G, node = create_nfr("emergent", epi=0.7, vf=1.2)
run_sequence(G, node, [SelfOrganization()])  # THOL: sub-EPIs created

# Transition to propagation
run_sequence(G, node, [Transition(), Resonance()])  # NAV → RA spreads

Configuration Parameters

Parameter	Default	Description
NAV_MIN_VF	0.01	Minimum structural frequency for transition
NAV_MAX_DNFR	1.0	Maximum ΔNFR for stable transition
NAV_STRICT_SEQUENCE_CHECK	False	Enable sequence validation warnings
MAX_SILENCE_DURATION	inf	Max silence duration before warning

Acceptance Criteria

• Create docs/source/operators/NAV_GUIDE.md with sections above
• Link from main operator documentation
• Include TNFR.pdf §2.3.11 references
• Add examples from definitions.py:Transition docstring
• Update README.md with NAV guide link

References

• TNFR.pdf Table 2.3 (glyphic structure typology)
• definitions.py:Transition (current docstring)
• docs/source/examples/SHA_CLINICAL_APPLICATIONS.md (documentation template)

Priority

LOW - Improves usability but not blocking

Affected Invariants (AGENTS.md)

• Invariant refactor: use relative imports within package #12: Documentation completeness