docs: create roadmap (4 phases)

.planning/REQUIREMENTS.md

@@ -98,44 +98,44 @@ Which phases cover which requirements. Updated during roadmap creation.
 
 | Requirement | Phase | Status |
 |-------------|-------|--------|
-| LIFE-01 | — | Pending |
+| LIFE-01 | Phase 1 | Pending |
-| LIFE-02 | — | Pending |
+| LIFE-02 | Phase 1 | Pending |
-| LIFE-03 | — | Pending |
+| LIFE-03 | Phase 1 | Pending |
-| LIFE-04 | — | Pending |
+| LIFE-04 | Phase 1 | Pending |
-| REND-01 | — | Pending |
+| CONF-01 | Phase 1 | Pending |
-| REND-02 | — | Pending |
+| SHEL-01 | Phase 1 | Pending |
-| REND-03 | — | Pending |
+| SHEL-02 | Phase 1 | Pending |
-| REND-04 | — | Pending |
+| REND-01 | Phase 2 | Pending |
-| REND-05 | — | Pending |
+| REND-02 | Phase 2 | Pending |
-| REND-06 | — | Pending |
+| REND-03 | Phase 2 | Pending |
-| REND-07 | — | Pending |
+| REND-04 | Phase 2 | Pending |
-| REND-08 | — | Pending |
+| REND-05 | Phase 2 | Pending |
-| REND-09 | — | Pending |
+| REND-06 | Phase 2 | Pending |
-| REND-10 | — | Pending |
+| REND-07 | Phase 2 | Pending |
-| NAV-01 | — | Pending |
+| REND-08 | Phase 2 | Pending |
-| NAV-02 | — | Pending |
+| REND-09 | Phase 2 | Pending |
-| NAV-03 | — | Pending |
+| REND-10 | Phase 2 | Pending |
-| NAV-04 | — | Pending |
+| NAV-05 | Phase 2 | Pending |
-| NAV-05 | — | Pending |
+| NAV-06 | Phase 2 | Pending |
-| NAV-06 | — | Pending |
+| NAV-07 | Phase 2 | Pending |
-| NAV-07 | — | Pending |
+| NAV-08 | Phase 2 | Pending |
-| NAV-08 | — | Pending |
+| NAV-09 | Phase 2 | Pending |
-| NAV-09 | — | Pending |
+| NAV-01 | Phase 3 | Pending |
-| NAV-10 | — | Pending |
+| NAV-02 | Phase 3 | Pending |
-| NAV-11 | — | Pending |
+| NAV-03 | Phase 3 | Pending |
-| BBS-01 | — | Pending |
+| NAV-04 | Phase 3 | Pending |
-| BBS-02 | — | Pending |
+| NAV-10 | Phase 3 | Pending |
-| LIVE-01 | — | Pending |
+| NAV-11 | Phase 3 | Pending |
-| LIVE-02 | — | Pending |
+| BBS-01 | Phase 4 | Pending |
-| CONF-01 | — | Pending |
+| BBS-02 | Phase 4 | Pending |
-| SHEL-01 | — | Pending |
+| LIVE-01 | Phase 4 | Pending |
-| SHEL-02 | — | Pending |
+| LIVE-02 | Phase 4 | Pending |
 
 **Coverage:**
 - v1 requirements: 32 total
-- Mapped to phases: 0
+- Mapped to phases: 32
-- Unmapped: 32 ⚠️
+- Unmapped: 0
 
 ---
 *Requirements defined: 2026-02-28*
-*Last updated: 2026-02-28 after initial definition*
+*Last updated: 2026-02-28 after roadmap creation*

.planning/ROADMAP.md

@@ -0,0 +1,79 @@
+# Roadmap: BBS-MD
+
+## Overview
+
+Four phases take this project from a bare Rust scaffold to a fully functional retro BBS markdown vault reader. Phase 1 establishes process safety — the login-shell deployment context means a crash without terminal restoration locks out every SSH user. Phase 2 builds the vault engine and renderer, producing the core content display pipeline. Phase 3 wires up link navigation, back/forward history, and keyboard link cycling, turning the viewer into an actual browser. Phase 4 adds the BBS aesthetic differentiators and live filesystem watching that make the experience feel like a real BBS rather than a generic TUI app.
+
+## Phases
+
+**Phase Numbering:**
+- Integer phases (1, 2, 3): Planned milestone work
+- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
+
+Decimal phases appear between their surrounding integers in numeric order.
+
+- [ ] **Phase 1: Safety Foundation** - Process lifecycle safety, shell integration, and configuration
+- [ ] **Phase 2: Vault Core and Rendering** - Markdown parsing pipeline and full content display
+- [ ] **Phase 3: Navigation and Links** - Link following, back/forward history, link cycling
+- [ ] **Phase 4: BBS Polish and Live Content** - Retro aesthetic, filesystem watching, directory listing
+
+## Phase Details
+
+### Phase 1: Safety Foundation
+**Goal**: The app launches as a login shell, handles crashes and disconnects without locking out users, and reads its configuration
+**Depends on**: Nothing (first phase)
+**Requirements**: LIFE-01, LIFE-02, LIFE-03, LIFE-04, SHEL-01, SHEL-02, CONF-01
+**Success Criteria** (what must be TRUE):
+  1. When the app panics, the SSH session returns to a usable terminal state instead of leaving it broken
+  2. When a user disconnects via SSH (SIGHUP) or the process is killed (SIGTERM), the app exits cleanly without corrupting the terminal
+  3. The app reads vault path and theme settings from bbs.toml and applies them on launch
+  4. The app exits cleanly when the user presses q or Ctrl+C, restoring the terminal
+  5. The app starts correctly when invoked as a login shell (argv[0] may have a leading dash)
+**Plans**: TBD
+
+### Phase 2: Vault Core and Rendering
+**Goal**: Users can read a markdown document — all standard constructs render correctly and content is scrollable
+**Depends on**: Phase 1
+**Requirements**: REND-01, REND-02, REND-03, REND-04, REND-05, REND-06, REND-07, REND-08, REND-09, REND-10, NAV-05, NAV-06, NAV-07, NAV-08, NAV-09
+**Success Criteria** (what must be TRUE):
+  1. User sees headers (H1-H6), bold, italic, inline code, fenced code blocks, lists, blockquotes, horizontal rules, and image placeholders rendered with distinct visual styling
+  2. User sees GFM tables rendered with aligned columns
+  3. User lands on index.md when the app starts; when index.md is missing, a readable error page is shown instead of a crash
+  4. User can scroll content longer than the terminal with j/k, arrow keys, and PgUp/PgDn
+  5. User sees keyboard hints in the status bar, box-drawing borders on panels, and a CGA-era retro color theme; the layout reflows correctly when the terminal is resized
+**Plans**: TBD
+
+### Phase 3: Navigation and Links
+**Goal**: Users can browse the vault by following links and navigating back and forward through their history
+**Depends on**: Phase 2
+**Requirements**: NAV-01, NAV-02, NAV-03, NAV-04, NAV-10, NAV-11
+**Success Criteria** (what must be TRUE):
+  1. User can press Enter on a highlighted wiki-link (`[[Page Name]]`) to navigate to that document
+  2. User can press Enter on a highlighted standard markdown link (`[text](path.md)`) to navigate to that document
+  3. User can press Backspace or a back key to return to the previous document, and then press a forward key to return to where they were
+  4. User can Tab-cycle between links on a page to select and follow them without using a mouse
+  5. User sees their current location (breadcrumb) in the status bar
+**Plans**: TBD
+
+### Phase 4: BBS Polish and Live Content
+**Goal**: The app feels like a real BBS — the index page has an ANSI art header, pages show last-updated timestamps, a vault directory is browsable, and content updates live without restarting
+**Depends on**: Phase 3
+**Requirements**: BBS-01, BBS-02, LIVE-01, LIVE-02
+**Success Criteria** (what must be TRUE):
+  1. The index.md page displays an ANSI art splash screen header
+  2. Each page shows the file's last-modified timestamp
+  3. When a markdown file in the vault is modified on disk, the currently displayed page auto-refreshes without the user doing anything
+  4. User can navigate to a vault-wide directory listing showing all available documents
+**Plans**: TBD
+
+## Progress
+
+**Execution Order:**
+Phases execute in numeric order: 1 → 2 → 3 → 4
+
+| Phase | Plans Complete | Status | Completed |
+|-------|----------------|--------|-----------|
+| 1. Safety Foundation | 0/TBD | Not started | - |
+| 2. Vault Core and Rendering | 0/TBD | Not started | - |
+| 3. Navigation and Links | 0/TBD | Not started | - |
+| 4. BBS Polish and Live Content | 0/TBD | Not started | - |

.planning/STATE.md

@@ -0,0 +1,65 @@
+# Project State
+
+## Project Reference
+
+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 1 - Safety Foundation
+
+## Current Position
+
+Phase: 1 of 4 (Safety Foundation)
+Plan: 0 of TBD in current phase
+Status: Ready to plan
+Last activity: 2026-02-28 — Roadmap created
+
+Progress: [░░░░░░░░░░] 0%
+
+## Performance Metrics
+
+**Velocity:**
+- Total plans completed: 0
+- Average duration: -
+- Total execution time: 0 hours
+
+**By Phase:**
+
+| Phase | Plans | Total | Avg/Plan |
+|-------|-------|-------|----------|
+| - | - | - | - |
+
+**Recent Trend:**
+- Last 5 plans: -
+- Trend: -
+
+*Updated after each plan completion*
+
+## Accumulated Context
+
+### Decisions
+
+Decisions are logged in PROJECT.md Key Decisions table.
+Recent decisions affecting current work:
+
+- Pre-Phase 1: Verify `edition = "2024"` compiles before changing to 2021 — leave it if `cargo build` succeeds
+- Pre-Phase 1: Use pulldown-cmark event-based approach for markdown parsing (not comrak)
+- Pre-Phase 1: No tokio/async runtime — synchronous event loop only
+- Pre-Phase 2: Choose wiki-link parsing strategy before implementation (regex pre-pass vs post-parse interception)
+
+### Pending Todos
+
+None yet.
+
+### Blockers/Concerns
+
+- **LIFE**: Panic hook and SIGHUP handling are highest priority — must land before any feature code
+- **REND**: Verify ratatui 0.30 custom Widget trait signature before building BBS widgets (changed between 0.28 and 0.29)
+- **NAV**: Path traversal via wiki-links must be addressed in Phase 3 link resolver — canonicalize and prefix-check every resolved path
+- **LIVE**: notify 8.x API must be verified at integration time; watch only current file (not full vault) to avoid inotify exhaustion
+
+## Session Continuity
+
+Last session: 2026-02-28
+Stopped at: Roadmap created, ready to plan Phase 1
+Resume file: None