From d537f04bf6ff3e9a219ba3ad5cee7e4d79889087 Mon Sep 17 00:00:00 2001 From: ruohki Date: Sat, 28 Feb 2026 20:49:44 +0100 Subject: [PATCH] docs(01): capture phase context --- .../phases/01-safety-foundation/01-CONTEXT.md | 69 +++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 .planning/phases/01-safety-foundation/01-CONTEXT.md diff --git a/.planning/phases/01-safety-foundation/01-CONTEXT.md b/.planning/phases/01-safety-foundation/01-CONTEXT.md new file mode 100644 index 0000000..7f2ac27 --- /dev/null +++ b/.planning/phases/01-safety-foundation/01-CONTEXT.md @@ -0,0 +1,69 @@ +# 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*