ghfs AGENTS.md

Rules

• CLI related logics, usage of @clack/prompts, console.log can only be under src/cli/
• GitHub related logics, usage of octokit can only be under src/providers/github/
• Pure/simple functions should better be under src/utils/ and be tested alongside.
• Avoid duplicating logics, refactor them to reuse.
• Always use pathe instead of node:path
• At this moment, we don't care about breaking changes at all, don't worry about migration or backward compatibility.

Keyboard accessibility (UI)

• Every interactive element under ui/ must be operable without a mouse. When adding a button, tab, pill, or dialog action, pair it with either (a) native Tab + Enter/Space — the default focus ring must be visible — or (b) a command registered in ui/composables/useAppCommands.ts, and render <Kbd command="..." /> next to it so the binding is discoverable.
• Text inputs & textareas get a single-key focus shortcut (e.g. / for search, n for comment). Escape already blurs focused inputs globally via ui/composables/useCommandHandler.ts — do not re-implement it. Tag the element with data-shortcut="<id>" so the command's run() can querySelector it.
• Submit-from-input (e.g. Cmd/Ctrl + Enter on a textarea): add a local @keydown.meta.enter / @keydown.ctrl.enter handler on the element. The global handler routes modifier combos to keybindings (e.g. mod+k opens the command palette); element-local Cmd/Ctrl+Enter handlers are still preferred for textarea submit so the registry stays focused on app-level actions.
• Prefer single-key shortcuts. The handler supports multi-key sequences via an 800 ms tail-match buffer (longer sequences win), and modifier combos via mod+x / mod+shift+x (alias mod resolves to Cmd on Mac, Ctrl elsewhere). Multi-key bindings are reserved for cases where every reasonable single letter already collides.
• Gate commands declaratively via the when field — a whenexpr string evaluated against useWhenContext() (e.g. 'hasActiveItem && activeItemState == "open"'). Add a new key to WhenContext in ui/composables/useWhenContext.ts rather than reaching for a JS predicate.
• Every command is callable from the command palette (mod+k / mod+shift+p). Use help: false on internal palette commands to keep them out of <HelpOverlay>, or help: '<when>' to scope visibility (e.g. help: 'hubMode').
• Every new btn-* variant in ui/uno.config.ts must include outline-none focus-visible:ring-2 focus-visible:ring-primary-500/40, matching the existing tab-trigger shortcut.
• The ? help overlay (ui/components/HelpOverlay.vue) auto-renders every registered command grouped by its category — keep each command title short and user-facing.