bbs-md/.planning/quick/1-arrow-key-navigation-and-directory-descr/1-PLAN.md

---
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"
---

<objective>
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
</objective>

<execution_context>
@.planning/STATE.md
</execution_context>

<context>
@src/app.rs
@src/vault.rs
</context>

<tasks>

<task type="auto">
  <name>Task 1: Add bare arrow key navigation and directory descriptions</name>
  <files>src/vault.rs, src/app.rs</files>
  <action>
**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<String>,
    pub description: Option<String>,  // NEW
}
```

Add a helper function `extract_frontmatter_description(path: &Path) -> Option<String>` 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).
  </action>
  <verify>
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.
  </verify>
  <done>
- 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)
  </done>
</task>

</tasks>

<verification>
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
</verification>

<success_criteria>
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.
</success_criteria>

<output>
After completion, create `.planning/quick/1-arrow-key-navigation-and-directory-descr/1-SUMMARY.md`
</output>