bbs-md/.planning/ROADMAP.md

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 (completed 2026-02-28)
• Phase 2: Vault Core and Rendering - Markdown parsing pipeline and full content display (completed 2026-02-28)
• Phase 3: Navigation and Links - Link following, back/forward history, link cycling (completed 2026-02-28)
• Phase 4: BBS Polish and Live Content - Retro aesthetic, filesystem watching, directory listing (completed 2026-03-01)

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: 3/3 plans complete Plans:

• 01-01-PLAN.md — Config loading, CLI parsing, and login shell detection
• 01-02-PLAN.md — Terminal init/restore, panic hook, and signal handling
• 01-03-PLAN.md — App event loop, exit behavior, and main.rs wiring

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: 3/3 plans complete Plans:

• 02-01-PLAN.md — Dependencies, vault file loading, and syntax highlighter
• 02-02-PLAN.md — Markdown-to-styled-lines renderer (all constructs)
• 02-03-PLAN.md — App integration: scrolling, status bar, error screen, startup wiring

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: 2/2 plans complete Plans:

• 03-01-PLAN.md — Renderer link extraction, wiki-link styling, and vault link resolution
• 03-02-PLAN.md — App navigation: history, link cycling, draw-time selection, breadcrumb status bar

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: 3/3 plans complete Plans:

• 04-01-PLAN.md — ANSI splash screen on index.md and file metadata in status bar
• 04-02-PLAN.md — Virtual directory listing via Directory wiki-link
• 04-03-PLAN.md — Live filesystem watching with auto-refresh

Progress

Execution Order: Phases execute in numeric order: 1 → 2 → 3 → 4

Phase	Plans Complete	Status	Completed
1. Safety Foundation	3/3	Complete	2026-02-28
2. Vault Core and Rendering	3/3	Complete	2026-02-28
3. Navigation and Links	2/2	Complete	2026-02-28
4. BBS Polish and Live Content	3/3	Complete	2026-03-01