Phase 1: Safety Foundation - Context

Gathered: 2026-02-28 Status: Ready for planning

## Phase Boundary

The app launches as a login shell, handles crashes and disconnects without locking out users, and reads its configuration from bbs.toml. This phase delivers process lifecycle safety and configuration loading — no content rendering, no navigation, no visual theming beyond what's needed to prove the app starts and exits cleanly.

## Implementation Decisions

Configuration shape

Config file lives next to the binary (same directory)
When bbs.toml is missing, use sensible defaults (vault defaults to ./vault/, default theme) — config file is optional
Phase 1 settings: vault_path and theme only — minimal config
Support --config /path/to/bbs.toml CLI flag to override config location
Strict TOML parsing — reject unknown keys to catch typos early
When vault path points to a nonexistent directory, show a friendly error and exit (don't launch the TUI)

Startup experience

Straight to content on launch — no splash screen, no delay, immediately show index.md
Clear the terminal on launch (clean slate, not alternate screen buffer) — immersive BBS feel, no shell artifacts
Login shell detection: strip the leading dash from argv[0] for compatibility
In login-shell mode, suppress 'q' to quit — prevents accidental SSH disconnects. Only Ctrl+C works as exit.

Failure messaging

On panic recovery: friendly message only — "Something went wrong. The app has exited safely." No technical details shown to user.
Panic details logged to stderr — captured by systemd journal or SSH output after exit, available for server admin
Config errors use BBS-themed tone — "SYSTEM ERROR: Config file corrupted at line 3. SysOp intervention required." style messaging

Exit behavior

BBS-style goodbye message on quit — retro signoff before terminal restores
Ctrl+C requires double-press to confirm — first press shows "Press again to quit", second press exits
In login-shell mode, Ctrl+C (double-press) is the only exit method — no alternative commands
Goodbye message displays for ~500ms (brief flash) before process exits

Claude's Discretion

Exact goodbye message text and formatting
Panic hook implementation approach
Signal handler registration strategy
Default theme values
Default vault path (./vault/ or similar)

## Specific Ideas

Error messages should feel like old-school BBS system messages — "SysOp intervention required" style
The clean-slate terminal clear reinforces the feeling of connecting to a remote BBS system
Double-press Ctrl+C pattern borrowed from modern CLI tools but fits the "are you sure you want to disconnect?" BBS feel

## Deferred Ideas

None — discussion stayed within phase scope

Phase: 01-safety-foundation Context gathered: 2026-02-28

2.9 KiB Raw Blame History