# BBS-MD

## What This Is

A retro-styled terminal markdown viewer that renders a vault of interconnected markdown files as browsable pages in a ratatui TUI. It acts like a BBS — the binary is set as a user's login shell so when someone SSHs in, they land directly in the markdown browser. Multiple users can connect and browse simultaneously.

## Core Value

Users can connect via SSH and seamlessly browse a vault of linked markdown documents with retro BBS aesthetics — no shell, no commands, just content navigation.

## Requirements

### Validated

- ✓ Rust binary with ratatui dependency — existing
- ✓ Cargo project scaffolded (edition 2024) — existing

### Active

- [ ] Render markdown files as styled terminal pages (headers, bold, lists, code blocks, tables)
- [ ] Support `[[wiki-links]]` and standard `[markdown](links)` between documents
- [ ] Web-like navigation: follow links, go back, history
- [ ] Landing page via index.md as entry point
- [ ] Filesystem watching for live content updates
- [ ] Multi-user read-only access (concurrent sessions)
- [ ] Retro BBS aesthetic (ANSI art, box-drawing characters)
- [ ] Show `[IMAGE: alt text]` placeholders for images
- [ ] Vault-relative link resolution (links resolve to .md files in vault)

### Out of Scope

- Embedded SSH/telnet server — the OS SSH daemon handles connections, this is just a terminal app
- Write/edit capabilities — read-only viewer
- User authentication or identity — the SSH daemon handles auth
- Mobile or web frontend — terminal only
- Image rendering beyond placeholders — no sixel/kitty graphics

## Context

- Existing Rust project with ratatui 0.30.0, crossterm backend, anyhow for errors
- Early stage — currently just scaffolding with hello world
- The binary will be configured as a user's default shell in `/etc/passwd` or sshd config
- Multiple SSH connections = multiple independent processes, each running the same binary against the same vault directory
- Vault is a directory of .md files, structure defined by the content creator
- Filesystem watching means the app picks up new/changed files without restart

## Constraints

- **Runtime**: Rust with ratatui — already chosen and scaffolded
- **Transport**: Pure terminal app, no networking code needed
- **Rendering**: Must work in standard VT100-compatible terminals
- **Concurrency**: Read-only access, so no file locking needed between sessions
- **Entry point**: Must handle being launched as a login shell gracefully

## Key Decisions

| Decision | Rationale | Outcome |
|----------|-----------|---------|
| No embedded SSH server | App is a login shell, SSH daemon handles transport | — Pending |
| Both wiki-links and markdown links | Maximum compatibility with existing vaults | — Pending |
| Filesystem watching over manual reload | Content should feel "live" like a web server | — Pending |
| index.md as landing page | Familiar convention, vault author controls the experience | — Pending |
| Read-only, no auth | Simplicity — SSH daemon handles access control | — Pending |

---
*Last updated: 2026-02-28 after initialization*