diff --git a/agents-2025-10-25.md b/agents-2025-10-25.md deleted file mode 100644 index ea6e717..0000000 --- a/agents-2025-10-25.md +++ /dev/null @@ -1,78 +0,0 @@ -## 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.