From 1d5ad4741179d2583a06e26ebb4a6e968dea7cdc Mon Sep 17 00:00:00 2001
From: ruohki <hi@till.md>
Date: Sat, 28 Feb 2026 20:18:58 +0100
Subject: [PATCH] docs: initialize project

---
 .planning/PROJECT.md | 66 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)
 create mode 100644 .planning/PROJECT.md

diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md
new file mode 100644
index 0000000..85d110f
--- /dev/null
+++ b/.planning/PROJECT.md
@@ -0,0 +1,66 @@
+# 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*