# Requirements: BBS-MD

**Defined:** 2026-02-28
**Core Value:** Users can connect via SSH and seamlessly browse a vault of linked markdown documents with retro BBS aesthetics

## v1 Requirements

Requirements for initial release. Each maps to roadmap phases.

### Process Lifecycle

- [x] **LIFE-01**: App installs panic hook that restores terminal state before printing error
- [x] **LIFE-02**: App handles SIGHUP/SIGTERM for clean shutdown on SSH disconnect
- [x] **LIFE-03**: App logs to file only, never writes to stderr/stdout after TUI init
- [x] **LIFE-04**: App handles broken pipe without crashing

### Markdown Rendering

- [ ] **REND-01**: User sees H1-H6 headers with visual hierarchy and styling
- [ ] **REND-02**: User sees bold, italic, and inline code rendered with terminal styling
- [x] **REND-03**: User sees fenced code blocks with syntax highlighting
- [ ] **REND-04**: User sees ordered and unordered lists with proper indentation
- [ ] **REND-05**: User sees blockquotes with visual distinction
- [ ] **REND-06**: User sees horizontal rules as visual separators
- [ ] **REND-07**: User sees `[IMAGE: alt text]` placeholders for images
- [ ] **REND-08**: User sees GFM tables rendered with aligned columns
- [ ] **REND-09**: User sees box-drawing borders on content panels
- [x] **REND-10**: User sees CGA-era retro color theme (cyan/magenta/green on dark)

### Navigation

- [x] **NAV-01**: User can follow `[[wiki-links]]` to other vault documents
- [x] **NAV-02**: User can follow standard `[text](path.md)` links to other documents
- [x] **NAV-03**: User can navigate back through history stack
- [x] **NAV-04**: User can navigate forward after going back
- [x] **NAV-05**: User can scroll content with j/k, arrows, PgUp/PgDn
- [x] **NAV-06**: User lands on index.md as the entry point
- [x] **NAV-07**: User sees graceful error page when a linked file is not found
- [x] **NAV-08**: User sees keyboard hints in status bar
- [x] **NAV-09**: App handles terminal resize without breaking layout
- [x] **NAV-10**: User sees links highlighted inline and can Tab-cycle between them
- [x] **NAV-11**: User sees breadcrumb / current location in status bar

### BBS Aesthetic

- [x] **BBS-01**: User sees ANSI art splash screen on index.md
- [x] **BBS-02**: User sees "last updated" file mtime on pages

### Live Content

- [x] **LIVE-01**: App watches filesystem for changes and auto-refreshes current page
- [x] **LIVE-02**: User can browse a vault-wide directory listing

### Configuration

- [x] **CONF-01**: App reads bbs.toml for vault path and theme configuration

### Shell Integration

- [x] **SHEL-01**: App exits cleanly with q or Ctrl+C, restoring terminal state
- [x] **SHEL-02**: App handles being launched as a login shell gracefully

## v2 Requirements

Deferred to future release. Tracked but not in current roadmap.

### Search

- **SRCH-01**: User can search across vault content
- **SRCH-02**: User sees search results with context snippets

### Advanced Rendering

- **ADVR-01**: User sees Mermaid/PlantUML diagrams rendered as ASCII art

### History

- **HIST-01**: User can view full navigation history overlay

### Interaction

- **INTR-01**: User can click links with mouse in supported terminals

## Out of Scope

| Feature | Reason |
|---------|--------|
| Embedded SSH/telnet server | App is a login shell — SSH daemon handles connections |
| Write/edit capabilities | Read-only viewer, hard guarantee |
| User authentication/identity | SSH daemon handles auth |
| Mobile or web frontend | Terminal only |
| Image rendering (sixel/kitty) | Standard terminals can't render images |
| Async runtime (tokio) | No async I/O needed — synchronous event loop is sufficient |

## Traceability

Which phases cover which requirements. Updated during roadmap creation.

| Requirement | Phase | Status |
|-------------|-------|--------|
| LIFE-01 | Phase 1 | Complete |
| LIFE-02 | Phase 1 | Complete |
| LIFE-03 | Phase 1 | Complete |
| LIFE-04 | Phase 1 | Complete |
| CONF-01 | Phase 1 | Complete (01-01) |
| SHEL-01 | Phase 1 | Complete |
| SHEL-02 | Phase 1 | Complete (01-01) |
| REND-01 | Phase 2 | Pending |
| REND-02 | Phase 2 | Pending |
| REND-03 | Phase 2 | Complete |
| REND-04 | Phase 2 | Pending |
| REND-05 | Phase 2 | Pending |
| REND-06 | Phase 2 | Pending |
| REND-07 | Phase 2 | Pending |
| REND-08 | Phase 2 | Pending |
| REND-09 | Phase 2 | Pending |
| REND-10 | Phase 2 | Complete |
| NAV-05 | Phase 2 | Complete |
| NAV-06 | Phase 2 | Complete |
| NAV-07 | Phase 2 | Complete |
| NAV-08 | Phase 2 | Complete |
| NAV-09 | Phase 2 | Complete |
| NAV-01 | Phase 3 | Complete |
| NAV-02 | Phase 3 | Complete |
| NAV-03 | Phase 3 | Complete |
| NAV-04 | Phase 3 | Complete |
| NAV-10 | Phase 3 | Complete |
| NAV-11 | Phase 3 | Complete |
| BBS-01 | Phase 4 | Complete (04-01) |
| BBS-02 | Phase 4 | Complete (04-01) |
| LIVE-01 | Phase 4 | Complete (04-03) |
| LIVE-02 | Phase 4 | Complete (04-02) |

**Coverage:**
- v1 requirements: 32 total
- Mapped to phases: 32
- Unmapped: 0

---
*Requirements defined: 2026-02-28*
*Last updated: 2026-03-01 after 04-03 execution — all Phase 4 requirements complete, project complete*