From 8adc00469140fa773745efb7437de566fa271fc2 Mon Sep 17 00:00:00 2001 From: ruohki Date: Sat, 28 Feb 2026 22:39:38 +0100 Subject: [PATCH] docs(03): capture phase context --- .../03-navigation-and-links/03-CONTEXT.md | 67 +++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 .planning/phases/03-navigation-and-links/03-CONTEXT.md diff --git a/.planning/phases/03-navigation-and-links/03-CONTEXT.md b/.planning/phases/03-navigation-and-links/03-CONTEXT.md new file mode 100644 index 0000000..bb187fd --- /dev/null +++ b/.planning/phases/03-navigation-and-links/03-CONTEXT.md @@ -0,0 +1,67 @@ +# 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*