docs(01): capture phase context

2026-02-28 20:49:44 +01:00
parent 4f6c9bcdc9
commit d537f04bf6
1 changed files with 69 additions and 0 deletions
@@ -0,0 +1,69 @@
+# Phase 1: Safety Foundation - Context
+
+**Gathered:** 2026-02-28
+**Status:** Ready for planning
+
+<domain>
+## 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.
+
+</domain>
+
+<decisions>
+## 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)
+
+</decisions>
+
+<specifics>
+## 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
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+None — discussion stayed within phase scope
+
+</deferred>
+
+---
+
+*Phase: 01-safety-foundation*
+*Context gathered: 2026-02-28*