4.9 KiB
4.9 KiB
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
- LIFE-01: App installs panic hook that restores terminal state before printing error
- LIFE-02: App handles SIGHUP/SIGTERM for clean shutdown on SSH disconnect
- LIFE-03: App logs to file only, never writes to stderr/stdout after TUI init
- 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
- 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
- REND-10: User sees CGA-era retro color theme (cyan/magenta/green on dark)
Navigation
- NAV-01: User can follow
[[wiki-links]]to other vault documents - NAV-02: User can follow standard
[text](path.md)links to other documents - NAV-03: User can navigate back through history stack
- NAV-04: User can navigate forward after going back
- NAV-05: User can scroll content with j/k, arrows, PgUp/PgDn
- NAV-06: User lands on index.md as the entry point
- NAV-07: User sees graceful error page when a linked file is not found
- NAV-08: User sees keyboard hints in status bar
- NAV-09: App handles terminal resize without breaking layout
- NAV-10: User sees links highlighted inline and can Tab-cycle between them
- NAV-11: User sees breadcrumb / current location in status bar
BBS Aesthetic
- BBS-01: User sees ANSI art splash screen on index.md
- BBS-02: User sees "last updated" file mtime on pages
Live Content
- LIVE-01: App watches filesystem for changes and auto-refreshes current page
- LIVE-02: User can browse a vault-wide directory listing
Configuration
- CONF-01: App reads bbs.toml for vault path and theme configuration
Shell Integration
- SHEL-01: App exits cleanly with q or Ctrl+C, restoring terminal state
- 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 | Pending |
| LIFE-02 | Phase 1 | Pending |
| LIFE-03 | Phase 1 | Pending |
| LIFE-04 | Phase 1 | Pending |
| CONF-01 | Phase 1 | Pending |
| SHEL-01 | Phase 1 | Pending |
| SHEL-02 | Phase 1 | Pending |
| REND-01 | Phase 2 | Pending |
| REND-02 | Phase 2 | Pending |
| REND-03 | Phase 2 | Pending |
| 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 | Pending |
| NAV-05 | Phase 2 | Pending |
| NAV-06 | Phase 2 | Pending |
| NAV-07 | Phase 2 | Pending |
| NAV-08 | Phase 2 | Pending |
| NAV-09 | Phase 2 | Pending |
| NAV-01 | Phase 3 | Pending |
| NAV-02 | Phase 3 | Pending |
| NAV-03 | Phase 3 | Pending |
| NAV-04 | Phase 3 | Pending |
| NAV-10 | Phase 3 | Pending |
| NAV-11 | Phase 3 | Pending |
| BBS-01 | Phase 4 | Pending |
| BBS-02 | Phase 4 | Pending |
| LIVE-01 | Phase 4 | Pending |
| LIVE-02 | Phase 4 | Pending |
Coverage:
- v1 requirements: 32 total
- Mapped to phases: 32
- Unmapped: 0
Requirements defined: 2026-02-28 Last updated: 2026-02-28 after roadmap creation