# Phase 1: Safety Foundation - Research

**Researched:** 2026-02-28
**Domain:** Rust TUI process lifecycle, signal handling, TOML configuration, terminal state management
**Confidence:** HIGH

<user_constraints>
## User Constraints (from CONTEXT.md)

### Locked 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)

### Deferred Ideas (OUT OF SCOPE)
None — discussion stayed within phase scope
</user_constraints>

<phase_requirements>
## Phase Requirements

| ID | Description | Research Support |
|----|-------------|-----------------|
| LIFE-01 | App installs panic hook that restores terminal state before printing error | `std::panic::set_hook` + `ratatui::restore()` pattern; crossterm `disable_raw_mode` + clear commands |
| LIFE-02 | App handles SIGHUP/SIGTERM for clean shutdown on SSH disconnect | `signal-hook` 0.4.3 `flag::register()` with `AtomicBool`; polled in event loop |
| LIFE-03 | App logs to file only, never writes to stderr/stdout after TUI init | Standard `std::fs::File` append logging; all TUI output through ratatui draw cycle only |
| LIFE-04 | App handles broken pipe without crashing | Match on `ErrorKind::BrokenPipe`; use `let _ =` for write results; avoid `unwrap()` on I/O |
| CONF-01 | App reads bbs.toml for vault path and theme configuration | `toml` 1.0.3 + `serde` 1.0.228; `#[serde(deny_unknown_fields)]` + `#[serde(default)]` |
| SHEL-01 | App exits cleanly with q or Ctrl+C, restoring terminal state | `ratatui::restore()` in exit path; crossterm `disable_raw_mode`; double-press Ctrl+C state machine |
| SHEL-02 | App handles being launched as a login shell gracefully | `std::env::args_os().next()` argv[0]; `strip_prefix("-")` on OsStr; suppress 'q' key when login mode |
</phase_requirements>

---

## Summary

Phase 1 establishes the safety envelope for the entire application: panic recovery, signal handling, config loading, and clean shutdown. The Rust ecosystem has mature, well-documented solutions for every requirement here. The primary stack is ratatui 0.30 (already a dependency) + crossterm 0.29 (already a transitive dependency) for terminal management, signal-hook 0.4.3 for UNIX signal handling, and toml 1.0.3 + serde 1.0.228 for configuration parsing. clap 4.5 handles the `--config` CLI flag.

The most important architectural decision this phase must navigate is the terminal initialization strategy. The user decision specifies **main screen buffer with a clear** rather than the alternate screen buffer. This means deliberately not using `ratatui::init()` (which enters alternate screen) and instead manually calling `enable_raw_mode()` + `execute!(stdout(), Clear(ClearType::All), MoveTo(0, 0))`. This is the biggest deviation from ratatui's defaults and must be implemented carefully to ensure `restore()` still works correctly on exit and panic.

The double-press Ctrl+C pattern is a small state machine: track a `last_ctrl_c: Option<Instant>` — if a second SIGINT arrives within ~2 seconds of the first, exit; otherwise reset and show the prompt message. Since there is no async runtime, signal handling is done via `signal-hook` flag polling inside the crossterm event loop rather than a dedicated thread.

**Primary recommendation:** Use `Terminal::with_options` with `Viewport::Fullscreen`, skip `EnterAlternateScreen`, issue a raw `Clear(ClearType::All) + MoveTo(0,0)` at startup, and build a single unified `shutdown()` function called from all exit paths (panic hook, signal handler, normal quit).

---

## Standard Stack

### Core
| Library | Version | Purpose | Why Standard |
|---------|---------|---------|--------------|
| ratatui | 0.30.0 | TUI framework, terminal draw cycle | Already a dependency; 0.30 has `init()`, `restore()`, `run()` convenience functions |
| crossterm | 0.29.0 | Terminal raw mode, clear, cursor, key events | Ratatui's default backend; already a transitive dep; cross-platform |
| signal-hook | 0.4.3 | SIGHUP/SIGTERM/SIGINT handling | Widest community support for synchronous multi-signal handling; no async needed |
| toml | 1.0.3+spec-1.1.0 | TOML config parsing | The canonical Rust TOML crate; serde integration built-in |
| serde | 1.0.228 | Derive-based deserialization for config struct | Required by toml crate; standard across all Rust config parsing |
| clap | 4.5.60 | `--config` CLI flag parsing | Industry standard; derive API is concise; supports `PathBuf` natively |

### Supporting
| Library | Version | Purpose | When to Use |
|---------|---------|---------|-------------|
| serde_derive | (bundled with serde) | `#[derive(Deserialize)]` macro | Needed for config struct; enable `features = ["derive"]` |
| std::sync::atomic::AtomicBool | stdlib | Signal flags for SIGHUP/SIGTERM | Polling in event loop without threads |
| std::panic | stdlib | Panic hook installation | `set_hook` + `take_hook` for custom panic handler |
| std::time::Instant | stdlib | Double Ctrl+C timing window | Track first press timestamp |

### Alternatives Considered
| Instead of | Could Use | Tradeoff |
|------------|-----------|----------|
| signal-hook | ctrlc crate | ctrlc only handles SIGINT by default; SIGHUP requires `termination` feature; signal-hook is more explicit and handles all needed signals |
| signal-hook | raw libc signal() | Unsafe, no async-signal-safety guarantees, error-prone |
| toml | config crate | config crate is heavier (multi-source merging); overkill for a single optional TOML file |
| clap | std::env::args() manual parsing | clap gives `--help`, `--version`, error messages for free; minimal boilerplate with derive |

**Installation:**
```toml
[dependencies]
ratatui = "0.30.0"          # already present
signal-hook = "0.4.3"
toml = "1.0.3"
serde = { version = "1.0", features = ["derive"] }
clap = { version = "4.5", features = ["derive"] }
```

---

## Architecture Patterns

### Recommended Project Structure
```
src/
├── main.rs          # Entry point: parse CLI, detect login shell, init terminal, run loop
├── config.rs        # Config struct, load_config(), path resolution
├── terminal.rs      # Terminal init/restore, panic hook, clear-on-start
├── signals.rs       # Signal handler setup (SIGHUP, SIGTERM, SIGINT flags)
└── app.rs           # App state, event loop, double-Ctrl+C state machine
```

### Pattern 1: Custom Terminal Initialization (No Alternate Screen)

**What:** Initialize ratatui on the main screen buffer rather than alternate screen. This is the immersive BBS approach — the TUI occupies the user's actual terminal, and on exit the goodbye message is visible in scroll history.

**When to use:** When the user decision specifies main screen buffer / BBS feel (which it does here).

**The key insight:** `ratatui::init()` enters alternate screen. To avoid this, use `Terminal::with_options` and manually enable raw mode + clear the screen.

```rust
// Source: https://docs.rs/ratatui/latest/ratatui/struct.Terminal.html
// Source: https://docs.rs/crossterm/latest/crossterm/terminal/index.html

use std::io::stdout;
use crossterm::{
    execute,
    terminal::{enable_raw_mode, disable_raw_mode, Clear, ClearType},
    cursor::MoveTo,
};
use ratatui::{backend::CrosstermBackend, Terminal, TerminalOptions, Viewport};

pub fn init_terminal() -> std::io::Result<Terminal<CrosstermBackend<std::io::Stdout>>> {
    enable_raw_mode()?;
    execute!(stdout(), Clear(ClearType::All), MoveTo(0, 0))?;
    let backend = CrosstermBackend::new(stdout());
    // Viewport::Fullscreen uses main screen, not alternate screen
    let options = TerminalOptions {
        viewport: Viewport::Fullscreen,
    };
    Terminal::with_options(backend, options)
}

pub fn restore_terminal() -> std::io::Result<()> {
    disable_raw_mode()?;
    // No LeaveAlternateScreen because we never entered it
    // Optionally: move cursor to bottom, print newline
    Ok(())
}
```

**Important:** `ratatui::restore()` calls `LeaveAlternateScreen` — do NOT use it if you never entered alternate screen. Call `disable_raw_mode()` directly.

### Pattern 2: Panic Hook with Friendly User Message

**What:** Replace the default panic hook with one that restores the terminal, prints a friendly BBS-themed message to the user (stdout/stderr), and logs technical details for the sysop.

**When to use:** Required (LIFE-01). Install before TUI init so any panic during init also triggers cleanup.

```rust
// Source: https://ratatui.rs/recipes/apps/panic-hooks/

use std::panic::{set_hook, take_hook};
use crossterm::terminal::disable_raw_mode;

pub fn install_panic_hook() {
    let original_hook = take_hook();
    set_hook(Box::new(move |panic_info| {
        // Restore terminal — use let _ to suppress errors (avoid double-panic)
        let _ = disable_raw_mode();
        // Print friendly message to terminal (user sees this)
        eprintln!("\r\n*** SYSTEM ERROR: An unexpected fault has occurred. ***");
        eprintln!("*** The BBS has exited safely. SysOp has been notified. ***\r");
        // Call original hook — prints backtrace to stderr (captured by journald/SSH log)
        original_hook(panic_info);
    }));
}
```

**Key principle from official docs:** "It's important to avoid panicking while restoring the terminal state, otherwise the original panic reason might be lost." — use `let _ =` for all restoration calls.

### Pattern 3: Signal Handling with AtomicBool Flags

**What:** Register SIGHUP and SIGTERM to set AtomicBool flags; poll those flags in the event loop. No dedicated thread needed.

**When to use:** Required (LIFE-02). Synchronous, no async runtime.

```rust
// Source: https://docs.rs/signal-hook/latest/signal_hook/flag/index.html

use std::sync::Arc;
use std::sync::atomic::{AtomicBool, Ordering};
use signal_hook::consts::signal::{SIGHUP, SIGTERM};
use signal_hook::flag as signal_flag;

pub struct Signals {
    pub terminate: Arc<AtomicBool>,
}

pub fn register_signals() -> std::io::Result<Signals> {
    let terminate = Arc::new(AtomicBool::new(false));
    // SIGTERM: systemd stop, kill command
    signal_flag::register(SIGTERM, Arc::clone(&terminate))?;
    // SIGHUP: SSH disconnect, terminal hangup
    signal_flag::register(SIGHUP, Arc::clone(&terminate))?;
    Ok(Signals { terminate })
}

// In event loop:
if signals.terminate.load(Ordering::Relaxed) {
    return Ok(ShutdownReason::Signal);
}
```

### Pattern 4: Double-Press Ctrl+C State Machine

**What:** Track the timestamp of the first Ctrl+C press. If a second arrives within a window (e.g., 2 seconds), exit. Otherwise reset and show a prompt.

**When to use:** Required (SHEL-01). This is purely application logic, no external library needed.

```rust
// In-process pattern — no external library required
use std::time::{Duration, Instant};

struct App {
    ctrl_c_pressed_at: Option<Instant>,
    is_login_shell: bool,
}

const DOUBLE_PRESS_WINDOW: Duration = Duration::from_secs(2);

impl App {
    fn handle_ctrl_c(&mut self) -> AppAction {
        match self.ctrl_c_pressed_at {
            Some(first) if first.elapsed() < DOUBLE_PRESS_WINDOW => {
                // Second press within window — exit
                AppAction::Quit
            }
            _ => {
                // First press (or timeout expired) — show prompt
                self.ctrl_c_pressed_at = Some(Instant::now());
                AppAction::ShowQuitPrompt // "Press Ctrl+C again to disconnect."
            }
        }
    }

    fn handle_q_key(&mut self) -> AppAction {
        if self.is_login_shell {
            AppAction::Nothing // suppress 'q' in login-shell mode
        } else {
            AppAction::Quit
        }
    }
}
```

**Note:** Crossterm sends `KeyCode::Char('c')` with `KeyModifiers::CONTROL` for Ctrl+C events when raw mode is enabled. SIGINT is also raised — but with signal-hook registered, the event loop catches it via the flag. Choose one: either handle via crossterm key events OR via signal flag. The crossterm key event approach is simpler for the double-press logic.

### Pattern 5: TOML Config Loading with Strict Parsing

**What:** Deserialize bbs.toml with serde; `deny_unknown_fields` rejects typos; `Default` trait provides fallbacks when file is missing.

```rust
// Source: https://docs.rs/toml/latest/toml/

use serde::Deserialize;
use std::path::PathBuf;

#[derive(Deserialize, Debug)]
#[serde(deny_unknown_fields)]
pub struct Config {
    #[serde(default = "default_vault_path")]
    pub vault_path: PathBuf,

    #[serde(default = "default_theme")]
    pub theme: String,
}

fn default_vault_path() -> PathBuf {
    PathBuf::from("./vault")
}

fn default_theme() -> String {
    "default".to_string()
}

impl Default for Config {
    fn default() -> Self {
        Config {
            vault_path: default_vault_path(),
            theme: default_theme(),
        }
    }
}

pub fn load_config(path: &PathBuf) -> Result<Config, ConfigError> {
    if !path.exists() {
        return Ok(Config::default()); // Missing file is fine
    }
    let text = std::fs::read_to_string(path)
        .map_err(|e| ConfigError::ReadError(e))?;
    let config: Config = toml::from_str(&text)
        .map_err(|e| ConfigError::ParseError(e))?;
    Ok(config)
}
```

**Config path resolution order:**
1. `--config /explicit/path` (clap CLI flag) → use that path
2. No flag → `executable_dir() / "bbs.toml"` (same directory as binary)

```rust
// Resolve executable directory
fn find_binary_dir() -> PathBuf {
    std::env::current_exe()
        .expect("Cannot determine executable path")
        .parent()
        .expect("Binary has no parent directory")
        .to_path_buf()
}
```

### Pattern 6: Login Shell Detection

**What:** When launched as a login shell, the kernel sets argv[0] to have a leading dash (e.g., `-bbs-md` instead of `bbs-md`). Strip it for clap compatibility and record the mode.

```rust
// Source: POSIX convention, std::env::args_os()
// Note: args_os() is preferred over args() for non-UTF-8 paths

pub fn detect_login_shell() -> bool {
    let argv0 = std::env::args_os().next()
        .unwrap_or_default();
    let argv0_str = argv0.to_string_lossy();
    argv0_str.starts_with('-')
}

// Stripping the dash for clap: rebuild args without leading dash in argv[0]
// Then pass to clap's Parser::parse_from()
pub fn args_for_clap() -> Vec<std::ffi::OsString> {
    let mut args: Vec<_> = std::env::args_os().collect();
    if let Some(first) = args.first_mut() {
        let s = first.to_string_lossy();
        if s.starts_with('-') {
            *first = s.trim_start_matches('-').to_string().into();
        }
    }
    args
}
```

### Pattern 7: CLI Flag Parsing with clap

```rust
// Source: https://docs.rs/clap/latest/clap/

use clap::Parser;
use std::path::PathBuf;

#[derive(Parser, Debug)]
#[command(name = "bbs-md", about = "BBS-style markdown reader")]
pub struct Cli {
    /// Path to bbs.toml configuration file
    #[arg(long = "config", short = 'c', value_name = "FILE")]
    pub config: Option<PathBuf>,
}
```

Then call `Cli::parse_from(args_for_clap())` to handle the login shell argv[0] stripping.

### Pattern 8: Goodbye Message with Timed Display

**What:** Show a brief BBS-style goodbye message after terminal is restored, then `std::thread::sleep` briefly before process exits.

```rust
// Terminal is already restored (raw mode off) at this point
// Print directly to stdout — immersive feel
pub fn show_goodbye() {
    println!("\r");
    println!("  +------------------------------------------+");
    println!("  |  Thank you for calling. Goodbye!         |");
    println!("  |  Carrier lost.                           |");
    println!("  +------------------------------------------+");
    println!("\r");
    std::thread::sleep(std::time::Duration::from_millis(500));
}
```

### Anti-Patterns to Avoid

- **Using `ratatui::init()` then trying to skip alternate screen:** `ratatui::init()` enters alternate screen unconditionally. Use `Terminal::with_options` instead.
- **Using `ratatui::restore()` when alternate screen was never entered:** This calls `LeaveAlternateScreen` unnecessarily. Build a custom `restore_terminal()` that only calls `disable_raw_mode()`.
- **Panicking inside the panic hook:** Any error in the cleanup code that itself panics will hide the original panic message. Use `let _ =` for all I/O in the hook.
- **Registering SIGINT via signal-hook AND handling Ctrl+C via crossterm key events:** Choose one. Crossterm key events are easier for the double-press state machine.
- **Writing to stdout/stderr in the TUI event loop after init:** All output must go through the ratatui draw cycle. Direct writes corrupt the terminal state.
- **`unwrap()` on broken pipe writes:** SSH connections can close mid-write. Every write after TUI init that might fail should use `let _ =` or match on `BrokenPipe`.
- **Calling `clap::parse()` without stripping the leading dash:** Clap will fail or emit unexpected errors because `-bbs-md` looks like a flag argument.

---

## Don't Hand-Roll

| Problem | Don't Build | Use Instead | Why |
|---------|-------------|-------------|-----|
| Signal handling | Manual `libc::signal()` calls | `signal-hook` 0.4.3 | async-signal-safety, race conditions, platform differences |
| TOML parsing | Custom string parser | `toml` + `serde` | TOML spec compliance, multi-line strings, escape sequences |
| CLI argument parsing | Manual `args()` iteration | `clap` 4.5 | `--help`, `--version`, error messages, type coercion — all free |
| Terminal state restoration | Track state manually | `disable_raw_mode()` from crossterm | crossterm tracks raw mode state internally |
| Panic hook chaining | Replace the hook entirely | `take_hook()` + `set_hook()` pattern | Preserves existing hooks from other libraries (e.g., color_eyre) |

**Key insight:** The signal and terminal safety domains have subtle edge cases (reentrancy, async-signal-safety, platform quirks) that make hand-rolled solutions dangerous. The libraries exist specifically because these are hard.

---

## Common Pitfalls

### Pitfall 1: ratatui::init() Enters Alternate Screen
**What goes wrong:** Calling `ratatui::init()` silently enters the alternate screen buffer. On exit or restore, the terminal switches back to the main screen — the goodbye message and TUI output disappear from scroll history.
**Why it happens:** `ratatui::init()` is documented to enter alternate screen; this is the TUI standard. The BBS immersive mode requires main screen.
**How to avoid:** Use `Terminal::with_options(backend, TerminalOptions { viewport: Viewport::Fullscreen })` and manually call `enable_raw_mode()` + `Clear`. Do not call `ratatui::restore()` — call `disable_raw_mode()` directly.
**Warning signs:** On exit, the terminal screen flashes back to pre-TUI state; previous shell output reappears.

### Pitfall 2: Double-Panic in the Panic Hook
**What goes wrong:** The panic hook itself panics (e.g., `unwrap()` on a failed `disable_raw_mode()`), which causes an abort with no useful output.
**Why it happens:** Terminal state restoration can fail if the fd is already closed (e.g., SSH disconnect).
**How to avoid:** Every line in the panic hook that can fail must use `let _ =`. Never `unwrap()` or `?` inside a panic hook.
**Warning signs:** App crashes with "panicked while panicking" message.

### Pitfall 3: Ctrl+C Handled Both by Signal Hook and Crossterm Key Events
**What goes wrong:** SIGINT is registered via signal-hook AND crossterm delivers a `Ctrl+C` key event. The application handles it twice, or the state machine gets confused.
**Why it happens:** In raw mode, crossterm delivers Ctrl+C as a key event. signal-hook also fires if registered. Both can be active simultaneously.
**How to avoid:** Pick ONE mechanism. For the double-press pattern, crossterm key events are simpler because you get the event directly in your event loop without threading. Register SIGHUP and SIGTERM via signal-hook (for SSH disconnect), but handle Ctrl+C / SIGINT purely as a crossterm key event.
**Warning signs:** App exits on first Ctrl+C despite double-press requirement, or shows "press again" message twice.

### Pitfall 4: Config Error Exits Before Terminal Init
**What goes wrong:** Config validation (vault path doesn't exist) exits the process with `eprintln!()` + `process::exit(1)` after the terminal is in raw mode — leaving the terminal broken.
**Why it happens:** Config loading happens early, but if terminal init precedes it, error output is garbled.
**How to avoid:** Load and validate config BEFORE initializing the terminal. Any error at that stage uses normal `eprintln!()` because raw mode is not yet active.
**Warning signs:** Terminal is stuck in raw mode after config error; user has to run `reset`.

### Pitfall 5: SIGHUP Not Handled, SSH Disconnect Orphans Process
**What goes wrong:** User disconnects SSH; the process keeps running because SIGHUP is not handled, leaving a zombie BBS session.
**Why it happens:** Rust programs do not handle SIGHUP by default.
**How to avoid:** Register SIGHUP with signal-hook → same `terminate` AtomicBool as SIGTERM. Check the flag at the top of every event loop iteration.
**Warning signs:** After SSH disconnect, the process shows in `ps aux`; terminal state on reconnect is corrupted.

### Pitfall 6: Broken Pipe Panic on SSH Close
**What goes wrong:** Mid-write, the SSH connection drops. Writing to stdout returns `EPIPE`. Rust converts this to `BrokenPipe` error. If the write is `unwrap()`-ed, the app panics.
**Why it happens:** Rust by default ignores SIGPIPE and propagates as `ErrorKind::BrokenPipe`. With `unwrap()`, any such error becomes a panic.
**How to avoid:** All writes to stdout/stderr after TUI init use `let _ =` or match on `ErrorKind::BrokenPipe`. Also check the `terminate` signal flag in the event loop — the process should be exiting cleanly before the next write attempt.
**Warning signs:** Panic messages in logs containing "Broken pipe" or "os error 32".

### Pitfall 7: Login Shell argv[0] Passed to clap
**What goes wrong:** When launched as `-bbs-md`, clap sees `-bbs-md` as the program name (argv[0]) and may fail or produce confusing errors because the name starts with a dash.
**Why it happens:** clap uses argv[0] for usage messages and may interpret it as a flag prefix.
**How to avoid:** Strip the leading dash from argv[0] before passing args to `Cli::parse_from()`. Detect login shell separately by checking the original argv[0] before stripping.
**Warning signs:** clap prints usage with `-bbs-md` as the program name, or fails to parse.

---

## Code Examples

Verified patterns from official sources:

### Complete Terminal Initialization (Main Screen, No Alternate Buffer)
```rust
// Source: https://docs.rs/ratatui/latest/ratatui/struct.Terminal.html
// Source: https://docs.rs/crossterm/latest/crossterm/terminal/index.html

use std::io::stdout;
use crossterm::{
    execute,
    terminal::{enable_raw_mode, disable_raw_mode, Clear, ClearType},
    cursor::MoveTo,
};
use ratatui::{backend::CrosstermBackend, Terminal, TerminalOptions, Viewport};

pub fn init_terminal() -> std::io::Result<Terminal<CrosstermBackend<std::io::Stdout>>> {
    enable_raw_mode()?;
    execute!(stdout(), Clear(ClearType::All), MoveTo(0, 0))?;
    let backend = CrosstermBackend::new(stdout());
    Terminal::with_options(backend, TerminalOptions {
        viewport: Viewport::Fullscreen,
    })
}

pub fn restore_terminal() {
    let _ = disable_raw_mode();
    // No LeaveAlternateScreen — we never entered it
    let _ = execute!(stdout(), crossterm::cursor::Show);
}
```

### Panic Hook
```rust
// Source: https://ratatui.rs/recipes/apps/panic-hooks/

use std::panic::{set_hook, take_hook};

pub fn install_panic_hook() {
    let original_hook = take_hook();
    set_hook(Box::new(move |panic_info| {
        let _ = crossterm::terminal::disable_raw_mode();
        let _ = crossterm::execute!(
            std::io::stdout(),
            crossterm::cursor::Show
        );
        // Friendly user message (visible in terminal)
        eprintln!("\r\n+--------------------------------------------+");
        eprintln!("| SYSTEM ERROR: An unexpected fault occurred.|");
        eprintln!("| The BBS has exited safely.                 |");
        eprintln!("| SysOp has been notified.                   |");
        eprintln!("+--------------------------------------------+\r");
        // Original hook prints panic details to stderr (captured by journald)
        original_hook(panic_info);
    }));
}
```

### Signal Registration
```rust
// Source: https://docs.rs/signal-hook/latest/signal_hook/flag/index.html

use std::sync::Arc;
use std::sync::atomic::{AtomicBool, Ordering};
use signal_hook::consts::signal::{SIGHUP, SIGTERM};
use signal_hook::flag as signal_flag;

pub struct SignalFlags {
    pub terminate: Arc<AtomicBool>,
}

pub fn register_signals() -> std::io::Result<SignalFlags> {
    let terminate = Arc::new(AtomicBool::new(false));
    signal_flag::register(SIGTERM, Arc::clone(&terminate))?;
    signal_flag::register(SIGHUP, Arc::clone(&terminate))?;
    Ok(SignalFlags { terminate })
}
```

### Config Struct
```rust
// Source: https://docs.rs/toml/latest/toml/
// Source: https://docs.rs/serde/latest/serde/

use serde::Deserialize;
use std::path::PathBuf;

#[derive(Deserialize, Debug)]
#[serde(deny_unknown_fields)]
pub struct Config {
    #[serde(default = "default_vault_path")]
    pub vault_path: PathBuf,

    #[serde(default = "default_theme")]
    pub theme: String,
}

fn default_vault_path() -> PathBuf { PathBuf::from("./vault") }
fn default_theme() -> String { "default".to_string() }

impl Default for Config {
    fn default() -> Self {
        Config { vault_path: default_vault_path(), theme: default_theme() }
    }
}

pub enum ConfigError {
    ReadError(std::io::Error),
    ParseError(toml::de::Error),
    VaultNotFound(PathBuf),
}

pub fn load_config(path: &PathBuf) -> Result<Config, ConfigError> {
    if !path.exists() {
        return Ok(Config::default());
    }
    let text = std::fs::read_to_string(path).map_err(ConfigError::ReadError)?;
    let config: Config = toml::from_str(&text).map_err(ConfigError::ParseError)?;
    if !config.vault_path.exists() {
        return Err(ConfigError::VaultNotFound(config.vault_path));
    }
    Ok(config)
}
```

### CLI Parsing with Login Shell Support
```rust
// Source: https://docs.rs/clap/latest/clap/

use clap::Parser;
use std::path::PathBuf;

#[derive(Parser, Debug)]
#[command(name = "bbs-md")]
pub struct Cli {
    #[arg(long = "config", short = 'c', value_name = "FILE")]
    pub config: Option<PathBuf>,
}

pub fn detect_login_shell() -> bool {
    std::env::args_os()
        .next()
        .map(|a| a.to_string_lossy().starts_with('-'))
        .unwrap_or(false)
}

pub fn parse_cli() -> Cli {
    // Strip leading dash from argv[0] before clap sees it
    let mut args: Vec<std::ffi::OsString> = std::env::args_os().collect();
    if let Some(first) = args.first_mut() {
        let stripped = first.to_string_lossy()
            .trim_start_matches('-')
            .to_string();
        *first = stripped.into();
    }
    Cli::parse_from(args)
}
```

---

## State of the Art

| Old Approach | Current Approach | When Changed | Impact |
|--------------|------------------|--------------|--------|
| Manual `Terminal::new()` + manual raw mode | `ratatui::init()` / `ratatui::restore()` | ratatui 0.28.1 (2024) | Simpler for standard use; but we need `Terminal::with_options` for main-screen mode |
| `ratatui::init()` + `ratatui::restore()` | `ratatui::run()` closure | ratatui 0.30.0 (2025) | Even simpler for alternate-screen apps; not applicable here (we skip alternate screen) |
| `ctrlc` crate for signal handling | `signal-hook` for multi-signal | Ongoing | signal-hook handles SIGHUP + SIGTERM without separate crates |

**Deprecated/outdated:**
- `crossterm 0.28` and earlier: Ratatui 0.30 uses crossterm 0.29; there are breaking changes in the API between majors. The Cargo.lock already has 0.29.0 — do not pin to 0.28.
- `tui-rs`: Predecessor to ratatui; fully deprecated. Not relevant here.

---

## Open Questions

1. **Ctrl+C vs SIGINT: Which to use for double-press?**
   - What we know: Crossterm delivers `Ctrl+C` as a key event in raw mode. signal-hook can also intercept SIGINT. Both work.
   - What's unclear: Whether to use the crossterm key event path or register SIGINT via signal-hook and check the flag.
   - Recommendation: Use crossterm key event (`KeyCode::Char('c') + KeyModifiers::CONTROL`) for the double-press state machine. Register SIGHUP + SIGTERM via signal-hook for SSH disconnect handling. Do NOT register SIGINT with signal-hook to avoid double handling.

2. **Viewport::Fullscreen on resize**
   - What we know: ratatui handles terminal resize events via `crossterm::event::Event::Resize`. `Viewport::Fullscreen` should redraw on resize.
   - What's unclear: Whether `Terminal::with_options(Viewport::Fullscreen)` without alternate screen has any edge cases on terminal resize.
   - Recommendation: Handle `Event::Resize` explicitly in the event loop and call `terminal.clear()` + redraw. Test on resize during Phase 2 (content rendering).

3. **BBS-themed error message formatting**
   - What we know: User wants "SYSTEM ERROR: Config file corrupted at line 3. SysOp intervention required." style.
   - What's unclear: Exact text for goodbye message, panic message, and config error variants (left to Claude's discretion).
   - Recommendation: Keep messages short, in ALL-CAPS for system-level errors, and use box-drawing ASCII art for the goodbye screen. Plan task should include the exact strings.

---

## Sources

### Primary (HIGH confidence)
- `https://docs.rs/ratatui/latest/ratatui/fn.init.html` — ratatui::init() enters alternate screen; `init_with_options` does not
- `https://docs.rs/ratatui/latest/ratatui/struct.Terminal.html` — Terminal::with_options(), TerminalOptions, Viewport
- `https://ratatui.rs/recipes/apps/panic-hooks/` — panic hook pattern with take_hook/set_hook and restore
- `https://docs.rs/signal-hook/latest/signal_hook/flag/index.html` — flag::register() with AtomicBool for SIGHUP/SIGTERM
- `https://docs.rs/crossterm/latest/crossterm/terminal/index.html` — enable_raw_mode, disable_raw_mode, Clear, ClearType
- `https://docs.rs/toml/latest/toml/` — toml::from_str(), current version 1.0.3+spec-1.1.0
- `cargo search` results — verified crate versions: signal-hook 0.4.3, toml 1.0.3, clap 4.5.60, serde 1.0.228

### Secondary (MEDIUM confidence)
- `https://docs.rs/ratatui/latest/ratatui/fn.init_with_options.html` — init_with_options does not enter alternate screen; verified with official docs
- `https://docs.rs/crossterm/latest/crossterm/cursor/struct.MoveTo.html` — MoveTo(0,0) for cursor home position; cursor module is separate from terminal module

### Tertiary (LOW confidence)
- WebSearch result: double-press Ctrl+C pattern from GitHub issue on opencode CLI — not in official docs, pattern is idiomatic but implementation details left to discretion

---

## Metadata

**Confidence breakdown:**
- Standard stack: HIGH — versions verified via `cargo search` and official docs.rs
- Architecture: HIGH — ratatui docs explicitly document Terminal::with_options, Viewport, and panic hook patterns; signal-hook flag API verified
- Pitfalls: HIGH for terminal/panic pitfalls (from official docs); MEDIUM for signal + crossterm interaction (from ecosystem knowledge)

**Research date:** 2026-02-28
**Valid until:** 2026-03-30 (stable libraries, 30-day window reasonable)