owlen/agents-2025-10-25.md

audit(keys): current bindings & commands

• Default Vim profile only maps 13 actions (model picker, focus cycling, palette, debug) leaving core editor/navigation keys hard-coded elsewhere, limiting customisation and discoverability (crates/owlen-tui/keymap.toml:1).
• Emacs profile mirrors the same minimal surface with Alt-based chords, lacking text editing staples like yank/kill rings or buffer navigation (crates/owlen-tui/keymap_emacs.toml:1).
• Normal-mode logic wires multi-key sequences (gg, dd, Ctrl+W splits) and focus chords directly in Rust, bypassing the registry and preventing remapping (crates/owlen-tui/src/chat_app.rs:5691).
• Command palette exposes 52 keywords but lacks grouping, fuzzy tags, and modern discoverability patterns (crates/owlen-tui/src/commands/mod.rs:12).
• Pane management, resize, and accessibility toggles rely on bespoke status messaging with limited visual affordances, creating inconsistency across panels (crates/owlen-tui/src/chat_app.rs:5800).

research recap (vim/emacs & modern TUI UX)

• Contemporary TUI stacks (e.g., Textual) ship keymap registries with runtime swapping, fuzzy command launcher, and discoverable overlays, setting a parity bar for custom apps.
• GNU Emacs emphasises mnemonic, consistent command families (C-x for control commands, M- for meta navigation) and discourages overloading chords without documentation.
• Vim ecosystem guidance encourages using : commands plus modal consistency, avoiding unremappable hard-coded sequences to keep leader mappings customisable.
• Modern UX trends for 2025 favour adaptive layouts, depth via dupal layers, and clear affordances even in minimalist shells, suggesting richer theming, animation, and responsive scaffolding.
• Emerging terminal UIs adopt layered “glass + neon” aesthetics with light/dark parity and accessible contrasts instead of monochrome blocks.
• CLI design critiques highlight the need for preview panes, keyboard hints, and status context to bridge novice gaps.

roadmap (Owlen UX parity sprint)

1) feat(keymap): rebuild binding registry with modal coverage

• Status: Complete — unified keymap tree with sequence-aware matching, binding export, and runtime introspection.
• Highlights:
  1. Replaced ad-hoc pending_key/pending_focus_chord logic with a trie-driven resolver supporting arbitrary sequences, timeouts, and per-mode registries (crates/owlen-tui/src/state/keymap.rs).
  2. Extended TOML schema (crates/owlen-tui/keymap.toml) to declare multi-step chords (gg, dd, Ctrl+W s, Ctrl+K ←), mapping them to new AppCommand variants consumed in chat_app.
  3. Added :keymap show to stream the active binding table into the transcript, aiding discoverability and regression review (crates/owlen-tui/src/chat_app.rs).
• Tests: cargo test -p owlen-tui (covers keymap parser + sequence resolution).

2) feat(keymap): enhance Emacs profile & leader ergonomics

• Why: Match Emacs conventions (C-x, C-c prefixes, yank/kill, buffer switching) and provide Vim leaders for workspace, tools, search.
• Implement: Flesh out Emacs profile with kill-ring commands, register C-x C-f, C-x C-s, M-g jumps, etc. Introduce configurable Vim leader (default space) with namespaced commands for provider/model, tools, layout.
• AC: Built-in keymaps cover ≥90% of documented commands; help overlay lists canonical chords.
• Tests: Snapshot tests for :keymap vim|emacs, runtime switch coverage, toml schema validation.

3) feat(commands): modern palette with tagging & fuzzy discovery

• Why: Current flat list scales poorly; modern TUIs expose grouped, searchable command centers with context previews.
• Implement: Introduce metadata (category, mode availability, keybinding). Replace static array with data-driven registry backing palette cards, filters, quick docs. Add inline preview for high-impact commands (:files, :model).
• AC: Typing focus shows grouped matches with key hints; palette supports tag filters (e.g., /agent).
• Tests: Command search integration test, snapshot for palette rendering, lint verifying metadata completeness.

4) feat(tui): adaptive layout & polish refresh

• Why: Align Owlen with 2025 TUI styling (responsive spacing, depth cues, animated transitions) while preserving accessibility.
• Implement: Build layout system with breakpoints (≤80 cols stacked, ≥120 cols split). Introduce layer tokens (frosted glass, neon accent) with configurable shadows, transitions, and focus rings. Add optional micro-animations for context gauges, pane toggles.
• AC: UI adapts seamlessly across 80/100/140-col snapshots; focus state and warnings remain perceivable in high-contrast mode.
• Tests: Ratatui snapshot suite for multiple terminal sizes/themes; golden tests for animation fallbacks when disabled.

5) feat(guidance): inline cheat-sheets & onboarding

• Why: Keyboard-rich TUIs need embedded guidance to bridge novices; industry examples surface dynamic hints and quick tours.
• Implement: Contextual overlay triggered via ? showing active keymap, top commands, search tips; first-run coach marks for focus chords and leader keys. Persist completion flags in config.
• AC: First launch displays onboarding flow; ? overlay updates with keymap swaps.
• Tests: Snapshot coverage for overlays; integration test ensuring onboarding flag persists.

6) feat(tui): status surface & toast overhaul

• Why: Current status text is terse; need richer multi-line feedback with icons, timers, action shortcuts.
• Implement: Replace single-line status with layered HUD (primary message, subtext, progress). Add toast API with severity icons, auto-dismiss timers, and keyboard hints.
• AC: Streaming, tool calls, rate limits show structured cards; toasts accessible via history panel.
• Tests: Unit tests for toast queue, snapshot for HUD states, integration verifying keyboard hints update per keymap.

7) docs(tui): publish UX & keybinding playbook

• Why: Documenting conventions reduces drift and eases contributor onboarding; aligns with Emacs/Vim guidelines.
• Implement: Author guide covering modal philosophy, command metadata schema, theming tokens, animation policy. Include migration notes for custom keymaps.
• AC: Docs indexed from README, changelog summarises parity steps.
• Tests: Link checker; sample custom keymap validated in CI.

8) test(tui): automated UX regression suite

• Why: Large visual refactor demands deterministic screenshots across modes & terminal sizes.
• Implement: Expand chat_snapshots.rs to cover normal/insert/visual/command states, both keymaps, accessibility toggles, and responsive breakpoints. Wire into CI with diff artifact upload.
• AC: Snapshot set protects ≥90% of critical panels; CI fails on visual drift.
• Tests: cargo test -p owlen-tui --test chat_snapshots with feature gates for animations.

9) chore(assets): scripted screenshot pipeline

• Why: We need gallery-quality imagery for docs/changelog while keeping it reproducible.
• Implement: Add a demo harness that stages representative scenes (model picker, usage header, tool call, accessibility modes) using deterministic seeds; render frames via ratatui TestBackend, export ANSI dumps, and convert to PNG with an ANSI→image tool (e.g., chafa). Provide a cargo xtask screenshots command and update docs to reference the generated assets.
• AC: Running cargo xtask screenshots regenerates all gallery files; README/docs reference the latest images.
• Tests: CI smoke test invoking the harness (PNG conversion optional via feature flag); checksum guard to detect drift.

10) feat(compression): adaptive transcript compactor with auto-toggle

• Why: Long chats blow past context windows; we need an owned compression pipeline that keeps history usable without manual pruning.
• Implement: Build a compression service that chunks stale turns, summarises via chosen model/tool, and rewrites history entries. Auto mode enabled by default; expose config flag (chat.auto_compress = true), CLI opt-out (--no-auto-compress), and runtime command (:compress auto on|off, :compress now). Provide granular settings (threshold tokens, model override, strategy).
• AC: Owlen transparently compresses once history exceeds threshold; users can toggle via config/CLI/command and view status. Compression metadata logged for audit.
• Tests: Unit test strategy selection; integration harness simulating long conversations verifying auto-trigger, manual command, and CLI flag precedence.