docs(04-01): complete splash screen and file metadata plan

.planning/ROADMAP.md

@@ -77,7 +77,7 @@ Plans:
   4. User can navigate to a vault-wide directory listing showing all available documents
 **Plans:** 3 plans
 Plans:
-- [ ] 04-01-PLAN.md — ANSI splash screen on index.md and file metadata in status bar
+- [x] 04-01-PLAN.md — ANSI splash screen on index.md and file metadata in status bar
 - [ ] 04-02-PLAN.md — Virtual directory listing via [[Directory]] wiki-link
 - [ ] 04-03-PLAN.md — Live filesystem watching with auto-refresh
 
@@ -91,4 +91,4 @@ Phases execute in numeric order: 1 → 2 → 3 → 4
 | 1. Safety Foundation | 3/3 | Complete    | 2026-02-28 |
 | 2. Vault Core and Rendering | 3/3 | Complete    | 2026-02-28 |
 | 3. Navigation and Links | 2/2 | Complete    | 2026-02-28 |
-| 4. BBS Polish and Live Content | 0/3 | Not started | - |
+| 4. BBS Polish and Live Content | 1/3 | In progress | - |

.planning/STATE.md

@@ -5,23 +5,23 @@
 See: .planning/PROJECT.md (updated 2026-02-28)
 
 **Core value:** Users can connect via SSH and seamlessly browse a vault of linked markdown documents with retro BBS aesthetics
-**Current focus:** Phase 3 COMPLETE — Plans 01 and 02 done (navigation, history, Tab-cycling, breadcrumbs all wired)
+**Current focus:** Phase 4 IN PROGRESS — Plan 01 done (splash screen, file metadata, all Phase 4 deps), Plans 02-03 remaining
 
 ## Current Position
 
-Phase: 3 of 4 (Navigation and Links) — COMPLETE
+Phase: 4 of 4 (BBS Polish and Live Content) — IN PROGRESS
-Plan: 2 of 2 in current phase (03-01 done, 03-02 done)
+Plan: 1 of 3 in current phase (04-01 done, 04-02 next)
-Status: 03-02 complete — navigation history, link cycling, breadcrumb status bar implemented
+Status: 04-01 complete — splash screen, file metadata in status bar, Phase 4 dependencies added
-Last activity: 2026-02-28 — Plan 02 complete (HistoryEntry, navigate_to/back/forward, Tab-cycling, REVERSED highlight, breadcrumb)
+Last activity: 2026-03-01 — Plan 01 complete (splash.rs, PageMeta, ansi-to-tui/notify/walkdir deps)
 
-Progress: [██████████] 100%
+Progress: [████████░░] 80%
 
 ## Performance Metrics
 
 **Velocity:**
-- Total plans completed: 7
+- Total plans completed: 8
-- Average duration: 2.8 min
+- Average duration: 2.9 min
-- Total execution time: 0.33 hours
+- Total execution time: 0.39 hours
 
 **By Phase:**
 
@@ -30,9 +30,10 @@ Progress: [██████████] 100%
 | 01-safety-foundation | 3 | 7 min | 2.3 min |
 | 02-vault-core-and-rendering | 3 | 9 min | 3.0 min |
 | 03-navigation-and-links | 2 | 7 min | 3.5 min |
+| 04-bbs-polish-and-live-content | 1 | 4 min | 4.0 min |
 
 **Recent Trend:**
-- Last 5 plans: 3 min, 2 min, 2 min, 4 min, 3 min
+- Last 5 plans: 2 min, 2 min, 4 min, 3 min, 4 min
 - Trend: Stable
 
 *Updated after each plan completion*

.planning/phases/04-bbs-polish-and-live-content/04-01-SUMMARY.md

@@ -0,0 +1,119 @@
+---
+phase: 04-bbs-polish-and-live-content
+plan: 01
+subsystem: ui
+tags: [ansi-to-tui, notify, walkdir, ratatui, rust, splash-screen, file-metadata, status-bar]
+
+# Dependency graph
+requires:
+  - phase: 03-navigation-and-links
+    provides: "navigate_to/back/forward with link_records, breadcrumb status bar, draw_status_bar()"
+provides:
+  - "src/splash.rs with load_splash() loading ANSI art from splash.txt via ansi-to-tui"
+  - "PageMeta struct and read_page_meta() with pure Gregorian date math in app.rs"
+  - "Splash prepend with link_record line_index offsetting in navigate_to/back/forward and initial load"
+  - "Status bar right side shows 'Last modified: Mon DD, YYYY | X.X KB' with graceful truncation"
+  - "All Phase 4 dependencies (notify=6.1, ansi-to-tui=8.0, walkdir=2.5) in Cargo.toml"
+affects: [04-02-live-reload, 04-03-directory-listing]
+
+# Tech tracking
+tech-stack:
+  added:
+    - "ansi-to-tui = 8.0 — ANSI SGR escape code parser targeting ratatui-core types"
+    - "notify = 6.1 — cross-platform filesystem watcher (for Phase 4 plan 02)"
+    - "walkdir = 2.5 — recursive directory traversal with depth tracking (for Phase 4 plan 03)"
+  patterns:
+    - "Splash prepend pattern: load_splash() returns Vec<Line<'static>>, prepend to markdown lines, offset link_records by splash_count + 1 (blank separator)"
+    - "Page metadata computed in App::new() and on every navigation from vault_path.join(current_path)"
+    - "Status bar graceful truncation: loop removing second-to-last right_part until left.len + right.len <= width"
+
+key-files:
+  created:
+    - "src/splash.rs — load_splash() reading splash.txt as Vec<u8>, parsing via IntoText trait"
+  modified:
+    - "Cargo.toml — added notify, ansi-to-tui, walkdir dependencies"
+    - "src/app.rs — PageMeta struct, read_page_meta(), unix_secs_to_ymd(), is_leap(), format_file_size(), page_meta field in App, splash logic in navigate_to/back/forward/handle_resize, metadata in draw_status_bar"
+    - "src/main.rs — splash prepend in initial index.md load, mod splash declaration"
+
+key-decisions:
+  - "App::new() computes page_meta internally from config.vault_path + current_path — keeps PageMeta private, no public type exposure needed"
+  - "splash_count = splash_lines.len() + 1 for the blank separator Line — all link_record line_index values offset by this amount to keep Tab-cycling correct"
+  - "Status bar truncation drops right_parts[hints_idx - 1] (the metadata item) progressively until bar fits — hints always kept as last item"
+  - "Hand-rolled Gregorian date math (unix_secs_to_ymd + is_leap) — avoids external time crate dependency, ~20 lines"
+  - "ratatui-core verified as single version via cargo tree — ansi-to-tui 8.0 unifies correctly with ratatui 0.30"
+
+patterns-established:
+  - "Splash pattern: load bytes with std::fs::read, call .into_text().ok()?, return .lines — all owned, 'static lifetime"
+  - "Link offset pattern: splash_count = splash_lines.len() + 1; for record in &mut link_records { record.line_index += splash_count; }"
+  - "Metadata pattern: read_page_meta(&vault_path.join(vault_relative)) after successful VaultDocument::Loaded"
+
+requirements-completed: [BBS-01, BBS-02]
+
+# Metrics
+duration: 4min
+completed: 2026-02-28
+---
+
+# Phase 4 Plan 01: BBS Polish - Splash Screen and File Metadata Summary
+
+**ANSI art splash screen loaded from splash.txt via ansi-to-tui 8.0 prepended to index.md, with file mtime and size in status bar using hand-rolled Gregorian date formatting**
+
+## Performance
+
+- **Duration:** 4 min
+- **Started:** 2026-02-28T22:46:19Z
+- **Completed:** 2026-02-28T22:50:00Z
+- **Tasks:** 2
+- **Files modified:** 4
+
+## Accomplishments
+
+- `src/splash.rs` module created with `load_splash()` that reads `splash.txt` as owned bytes, parses ANSI SGR codes via `IntoText` trait, returns `Vec<Line<'static>>` — gracefully returns `None` if file missing
+- Splash prepend wired into all navigation paths (`navigate_to`, `navigate_back`, `navigate_forward`, initial load in `main.rs`, and `handle_resize`) with correct `link_record.line_index` offsetting so Tab-cycling still targets the right lines
+- `PageMeta` struct and `read_page_meta()` added to `app.rs` — reads `std::fs::metadata()`, converts mtime to "Feb 25, 2026" format with pure Gregorian arithmetic, formats size as "X.X KB"
+- Status bar right side now shows "Last modified: Mon DD, YYYY | X.X KB" with graceful truncation that drops metadata before hints when terminal is narrow
+- All three Phase 4 crate dependencies (`notify = "6.1"`, `ansi-to-tui = "8.0"`, `walkdir = "2.5"`) added to `Cargo.toml` — verified single `ratatui-core v0.1.0` in dependency tree
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Add Phase 4 deps and create splash module** - `6aa5a94` (chore)
+2. **Task 2: Wire splash prepend and file metadata to status bar** - `27139cf` (feat)
+
+## Files Created/Modified
+
+- `src/splash.rs` - `load_splash()` reading vault root `splash.txt` via `IntoText` into `Vec<Line<'static>>`
+- `Cargo.toml` - Added `notify = "6.1"`, `ansi-to-tui = "8.0"`, `walkdir = "2.5"`
+- `src/app.rs` - `PageMeta`, `read_page_meta()`, `unix_secs_to_ymd()`, `is_leap()`, `format_file_size()`; `page_meta` field on `App`; splash prepend in all navigation paths; metadata display in `draw_status_bar()`
+- `src/main.rs` - `mod splash` declaration; splash prepend with `link_record` offset in initial `index.md` load
+
+## Decisions Made
+
+- `App::new()` computes `page_meta` itself from `config.vault_path` + `current_path` — avoids making `PageMeta` pub while keeping initialization clean
+- `splash_count = splash_lines.len() + 1` — the +1 accounts for the blank separator `Line::default()` between splash art and markdown content
+- Status bar graceful truncation loops removing `right_parts[hints_idx - 1]` (the metadata string) progressively; hints always kept as the last item
+- Hand-rolled Gregorian math in `unix_secs_to_ymd()` — clean ~20 lines, no chrono/gregorian dependency needed
+
+## Deviations from Plan
+
+None - plan executed exactly as written. The plan's `App::new()` signature included `page_meta` as a parameter, but I instead computed it internally in `App::new()` to keep `PageMeta` private. This is a minor structural refinement that improves encapsulation without changing observable behavior.
+
+## Issues Encountered
+
+None. The `ansi-to-tui 8.0` + `ratatui 0.30` type unification worked correctly without needing an explicit `ratatui-core` pin — `cargo tree | grep ratatui-core` showed a single `v0.1.0` with `(*)` deduplication markers as expected.
+
+## User Setup Required
+
+Optional: Create `splash.txt` in the vault root containing ANSI art (CGA palette, block characters). If the file is absent, index.md renders normally with no error.
+
+## Next Phase Readiness
+
+- Phase 4 Plan 02 (live reload via `notify`) can now start — `notify = "6.1"` is already in `Cargo.toml`
+- Phase 4 Plan 03 (directory listing via `walkdir`) can start — `walkdir = "2.5"` is in `Cargo.toml`
+- `load_splash()` in `splash.rs` is pub and available for future plans
+- All navigation paths already handle splash prepend consistently
+
+---
+*Phase: 04-bbs-polish-and-live-content*
+*Completed: 2026-02-28*