docs: session navigation keybind documentation mismatch with actual behavior #16462

Problem

The current documentation for subagent session navigation keybinds does not match the actual implementation behavior, causing user confusion.

Current Documentation Says

In agents.mdx:

When subagents create their own child sessions, you can navigate between the parent session and all child sessions using:

• \u003cLeader>+Right (or your configured session_child_cycle keybind) to cycle forward through parent → child1 → child2 → ... → parent
• \u003cLeader>+Left (or your configured session_child_cycle_reverse keybind) to cycle backward

In keybinds.mdx example:

"session_child_cycle": "\u003cleader>right",
"session_child_cycle_reverse": "\u003cleader>left",
"session_parent": "\u003cleader>up",

Actual Behavior

Since PR #14814 (merged 2026-02-27), the navigation model changed to a hierarchical flow:

1. From parent session: Use session_child_first (default: \u003cleader>+down) to enter the first child session

2. Once in child session: Use bare arrow keys to navigate:

   • right (not \u003cleader>+right) → next child session
   • left (not \u003cleader>+left) → previous child session
   • up (not \u003cleader>+up) → return to parent session

3. Availability gating: Since PR fix(opencode): disable session navigation commands when no parent session #15762 (merged 2026-03-03), the session_child_cycle, session_child_cycle_reverse, and session_parent commands are only enabled when session().parentID exists (i.e., when you're already in a child session).

Evidence / Timeline

Current Code Defaults

// packages/opencode/src/config/config.ts
session_child_first: "\u003cleader>down",      // Enter child from parent
session_child_cycle: "right",               // Next child (bare key)
session_child_cycle_reverse: "left",        // Previous child (bare key)
session_parent: "up",                       // Return to parent (bare key)

Impact

Users following current documentation try \u003cleader>+left/right from parent session and it doesn't work, leading to confusion (see #4180, #4292).

Suggested Fix

Update documentation to reflect:

1. The hierarchical navigation flow (enter first, then cycle)
2. Actual default keybinds (bare arrow keys for cycling)
3. The requirement to be in a child session for cycle commands to be available

Related: #4180, #4292, #14814, #15762