stack-nudge: Instructions file for Codex

AGENTS.md

Guidance for AI agents working in this repo. CLAUDE.md is a symlink to this file, so edit this one.

Keyboard navigation

The panel is meant to be driven entirely from the keyboard, and every page should feel like the same app. Before adding or changing a binding, check it against the rules below and against the page that already does the same thing. If a change has to break a rule, say why in a comment at the binding and add it to the known exceptions at the end of this section.

Key routing lives in panel/Panel.swift. panelHandlesGlobalKey owns the keys that mean the same thing everywhere, and panelHandlesKey has one branch per nav.mode for the rest. Selection and value state live on PanelNav.

Keys that mean the same thing on every page

These are handled once, in panelHandlesGlobalKey, which FloatingPanel.sendEvent calls before the first responder sees the key. That is what makes them work while a text field has focus too. Don't bind them in a page's branch, and don't give a text field its own handling for them (.onExitCommand and the like): it can never fire.

Cancelling a field puts it back the way it was before you started and hands the keyboard back to its page. Recording a shortcut counts as editing one: cancelling keeps the old shortcut. A search, filter or new-entry field empties. A field holding a value goes back to that value: a rename keeps the old name, an extension config field its saved value. cancelField in Panel.swift does this per page, so a page that adds a text field adds its case there. The key that cancelled, or the combo a recording took, may still be held when the field lets go, so GlobalKeyRouter swallows its autorepeat until a fresh press.