bbs-md/.planning/phases/03-navigation-and-links/03-CONTEXT.md

Phase 3: Navigation and Links - Context

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

## Phase Boundary

Users can browse the vault by following wiki-links and standard markdown links, navigating back/forward through their history, and Tab-cycling between links on a page. The status bar shows breadcrumb location and navigation state. Creating/editing documents, search, and directory listing are separate phases.

## Implementation Decisions

Link appearance & cycling

• Links displayed as bracket-wrapped text with color: [Link Text] — fits the retro BBS aesthetic
• Selected link (via Tab cycling) shown with inverted colors (foreground/background swap)
• Tab cycling wraps around — after the last link, Tab returns to the first link on the page
• When Tab-cycling to an off-screen link, the view auto-scrolls to center the selected link on screen

Breadcrumb & status bar

• Current location shown as breadcrumb trail with separator: docs > guides > getting-started
• File extensions (.md) stripped from breadcrumb display
• Back/forward indicators shown when history exists (e.g. < Back | Forward >) — hidden when no history in that direction
• Link cycling index displayed when a link is selected: Link 3/7

Wiki-link resolution

• Case-insensitive matching: [[Getting Started]] matches getting-started.md, Getting-Started.md, etc.
• Space-to-filename mapping tries multiple strategies: hyphens first, then underscores, then literal spaces
• Broken wiki-links shown inline as red/strikethrough text — user sees it's broken without navigating
• Subpaths supported: [[guides/Getting Started]] resolves to guides/getting-started.md

History behavior

• Scroll position restored when navigating back — puts you exactly where you were
• Selected link restored when navigating back — full state restoration
• Unlimited history depth — full session history preserved
• Forward stack cleared when following a new link after going back (browser-style fork behavior)

Claude's Discretion

• Exact keybindings for back/forward (Backspace, Alt+Left/Right, etc.)
• Link resolution search order for ambiguous matches
• Error page design for broken link navigation attempts
• Breadcrumb separator character and styling

## Specific Ideas

• Bracket-wrapped links [Link Text] give a classic BBS/terminal hyperlink feel
• Inverted-color selection mirrors how BBS menus traditionally highlighted the active item
• Browser-style history (clear forward on fork, restore scroll+selection on back) is the mental model

## Deferred Ideas

None — discussion stayed within phase scope

---

Phase: 03-navigation-and-links Context gathered: 2026-02-28