# Phase 3: Navigation and Links - Context

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

<domain>
## 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.

</domain>

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

</decisions>

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

</specifics>

<deferred>
## Deferred Ideas

None — discussion stayed within phase scope

</deferred>

---

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