From 05a301ae638645371a7caffca468217d7467f534 Mon Sep 17 00:00:00 2001 From: ruohki Date: Sat, 28 Feb 2026 20:32:34 +0100 Subject: [PATCH] docs: define v1 requirements --- .planning/REQUIREMENTS.md | 141 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 141 insertions(+) create mode 100644 .planning/REQUIREMENTS.md diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md new file mode 100644 index 0000000..032273f --- /dev/null +++ b/.planning/REQUIREMENTS.md @@ -0,0 +1,141 @@ +# 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 | — | Pending | +| LIFE-02 | — | Pending | +| LIFE-03 | — | Pending | +| LIFE-04 | — | Pending | +| REND-01 | — | Pending | +| REND-02 | — | Pending | +| REND-03 | — | Pending | +| REND-04 | — | Pending | +| REND-05 | — | Pending | +| REND-06 | — | Pending | +| REND-07 | — | Pending | +| REND-08 | — | Pending | +| REND-09 | — | Pending | +| REND-10 | — | Pending | +| NAV-01 | — | Pending | +| NAV-02 | — | Pending | +| NAV-03 | — | Pending | +| NAV-04 | — | Pending | +| NAV-05 | — | Pending | +| NAV-06 | — | Pending | +| NAV-07 | — | Pending | +| NAV-08 | — | Pending | +| NAV-09 | — | Pending | +| NAV-10 | — | Pending | +| NAV-11 | — | Pending | +| BBS-01 | — | Pending | +| BBS-02 | — | Pending | +| LIVE-01 | — | Pending | +| LIVE-02 | — | Pending | +| CONF-01 | — | Pending | +| SHEL-01 | — | Pending | +| SHEL-02 | — | Pending | + +**Coverage:** +- v1 requirements: 32 total +- Mapped to phases: 0 +- Unmapped: 32 ⚠️ + +--- +*Requirements defined: 2026-02-28* +*Last updated: 2026-02-28 after initial definition*