---
phase: quick-1
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
- src/app.rs
- src/vault.rs
autonomous: true
requirements: [ARROW-NAV, DIR-DESC]
must_haves:
truths:
- "Bare Left arrow navigates back in history (same as Backspace)"
- "Bare Right arrow navigates forward in history (same as Alt+Right)"
- "Up/Down arrows already scroll (no change needed, just verify)"
- "Directory listing shows description text beside each file entry"
- "Descriptions come from YAML frontmatter 'description' field in .md files"
- "Descriptions are truncated to fit available terminal width"
artifacts:
- path: "src/app.rs"
provides: "Arrow key bindings + description display in build_directory_lines"
contains: "KeyCode::Left"
- path: "src/vault.rs"
provides: "DirEntry with description field, frontmatter parsing"
contains: "description"
key_links:
- from: "src/vault.rs"
to: "src/app.rs"
via: "DirEntry.description field consumed by build_directory_lines()"
pattern: "entry\\.description"
---
Add bare arrow key navigation (Left=back, Right=forward) and show YAML frontmatter descriptions beside files in the directory listing.
Purpose: Better keyboard ergonomics and richer directory browsing experience.
Output: Updated app.rs and vault.rs
@.planning/STATE.md
@src/app.rs
@src/vault.rs
Task 1: Add bare arrow key navigation and directory descriptions
src/vault.rs, src/app.rs
**Part A: Arrow keys in app.rs handle_key()**
In `handle_key()`, add bare Left and Right arrow cases. These must go AFTER the existing `Alt+Left` / `Alt+Right` matches (lines ~495-500) but BEFORE the scroll keys. Add these two arms:
```rust
KeyCode::Left => {
self.navigate_back();
}
KeyCode::Right => {
self.navigate_forward();
}
```
Place them right after the `KeyCode::Right if key.modifiers.contains(KeyModifiers::ALT)` arm (around line 500), before the scroll section comment. The match order matters: Alt+Left is checked first (guard), then bare Left falls through to the unguarded arm.
Up/Down already work for scrolling (line 502-506, paired with j/k). No changes needed there.
Update the doc comment on `handle_key()` to mention Left/Right arrow keys for back/forward.
**Part B: Frontmatter parsing in vault.rs**
Add a `description` field to `DirEntry`:
```rust
pub struct DirEntry {
pub depth: usize,
pub name: String,
pub is_dir: bool,
pub vault_path: Option,
pub description: Option, // NEW
}
```
Add a helper function `extract_frontmatter_description(path: &Path) -> Option` in vault.rs:
- Read the first ~20 lines of the file (use `BufReader` + `lines().take(20)` to avoid reading entire large files)
- Check if line 1 is exactly `---`
- Scan for `description:` line (case-sensitive key, value after colon, trimmed)
- Stop scanning at the closing `---` line
- Return `Some(description_string)` or `None`
- Handle both bare `description: some text` and quoted `description: "some text"` (strip outer quotes if present)
Call `extract_frontmatter_description` in `list_vault_files()` for each .md file entry, passing the full path from `entry.path()`. Set `description: None` for directory entries.
**Part C: Display descriptions in build_directory_lines() in app.rs**
Modify the file entry rendering in `build_directory_lines()` to show descriptions. For each file entry that has a description:
```
[filename] description text here, truncated...
```
Use a dimmed/dark gray style for the description (Color::DarkGray) to visually separate it from the link text. Truncate the description so the total line width does not exceed 78 characters (or a reasonable fixed width). If the description would overflow, truncate and append "...".
The format should be:
- `{indent}[{name}] {description}` where description is in DarkGray
- Two spaces between the bracketed name and the description
- Description truncated to fit within ~78 char total line width
For entries without a description, display as before (just the bracketed name).
Note: The `span_len` in `LinkRecord` must still only cover the `[name]` portion, NOT the description. The description span is separate and not part of the link. Adjust `col_offset` to remain correct (it's the indent width, unchanged).
Run `cargo build` from the project root. Expect clean compilation with no errors and no new warnings.
Run `cargo clippy` to check for lint issues.
- Bare Left arrow calls navigate_back, bare Right arrow calls navigate_forward
- Alt+Left and Alt+Right still work as before (matched first due to guard)
- Up/Down still scroll as before (unchanged)
- DirEntry has a description field populated from YAML frontmatter
- Directory listing shows descriptions in DarkGray beside file entries
- Descriptions are truncated to avoid line overflow
- All existing functionality preserved (no regressions)
1. `cargo build` succeeds
2. `cargo clippy` passes
3. Manual test: run the app, navigate to directory listing, verify descriptions appear
4. Manual test: press Left arrow to go back, Right arrow to go forward
5. Manual test: Up/Down arrows still scroll content
Arrow keys provide full navigation: Up/Down scroll, Left goes back, Right goes forward. Directory listing shows frontmatter descriptions beside each file entry in a subdued style.