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

phase, plan, type, wave, depends_on, files_modified, autonomous, requirements, must_haves

phase	plan	type	wave	depends_on	files_modified	autonomous	requirements	must_haves
quick-1	01	execute	1		src/app.rs src/vault.rs	true	ARROW-NAV DIR-DESC	truths artifacts key_links 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 path provides contains src/app.rs Arrow key bindings + description display in build_directory_lines KeyCode::Left path provides contains src/vault.rs DirEntry with description field, frontmatter parsing description from to via pattern src/vault.rs src/app.rs DirEntry.description field consumed by build_directory_lines() 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

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

@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:

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:

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). 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

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

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