Phase 2: Vault Core and Rendering - Context

Gathered: 2026-02-28 Status: Ready for planning

## Phase Boundary

Markdown parsing pipeline and full content display. Users can read a markdown document with all standard constructs rendered correctly and content is scrollable. This phase delivers the vault engine (loading files from vault_path), pulldown-cmark based markdown-to-styled-lines conversion, ratatui rendering, scrolling, status bar, and error handling for missing files. Navigation between documents and link following are Phase 3.

## Implementation Decisions

Color palette & text styling

Classic CGA 16-color palette for accent elements (headers, code, links, emphasis markers)
Body text uses terminal default foreground/background — respects user's TERM color scheme
CGA accent colors only override for specific elements, not body text
Heading levels (H1-H6) distinguished by both color AND decorators (e.g. H1 = bright cyan + ══ underline, H2 = bright yellow, H3 = green, etc.)
Bold uses terminal bold attribute, italic uses terminal italic attribute, inline code uses terminal styling — modern terminals support these natively
No need to fall back to color-only for bold/italic since SSH users have modern terminal emulators

Screen layout & chrome

No content borders — content goes edge-to-edge, maximizing reading space
Single status bar at the bottom only (vim-style)
Status bar content: current filename on the left, keyboard hints (q:Quit j/k:Scroll) on the right
Status bar style: reverse video (inverted colors) — classic terminal status bar look
No top bar, no title bar, no breadcrumb bar (breadcrumb comes in Phase 3)

Code blocks & tables

Fenced code blocks get syntax highlighting using CGA palette colors (cyan keywords, green strings, etc.)
Code blocks framed with indent + colored background + rounded-corner box-drawing borders (╭─╮│╰─╯)
GFM tables rendered with full box-drawing grid (┌┬┐├┼┤└┴┘) — classic DOS table look
Table header row styled with bold + CGA accent color (e.g. bright cyan or yellow)

Scrolling

j/k and arrow keys scroll one line at a time
PgUp/PgDn scroll a full page height
No splash screen on startup — go straight to content

Claude's Discretion

Exact CGA color assignments per heading level (H1-H6)
Exact decorator style per heading level (═══ vs ─── vs none)
Syntax highlighting color mapping (which CGA color for keywords, strings, comments, etc.)
Blockquote visual style
Horizontal rule style
Image placeholder styling
List bullet/number styling
Scroll boundary behavior (stop or bounce)

## Specific Ideas

index.md renders as a regular page — no special landing treatment in Phase 2 (ANSI art splash is Phase 4)
Missing index.md shows a retro BBS-style error screen with box-drawing border, "No index.md found" message, vault path shown, and hint to create one
No startup splash or loading indicator — fast and no-nonsense

## Deferred Ideas

None — discussion stayed within phase scope

Phase: 02-vault-core-and-rendering Context gathered: 2026-02-28

3.2 KiB Raw Permalink Blame History