docs: detail shell interface design decisions for phase 1.4

Add session context, shell configuration, and transparent I/O recording
design notes based on exploration of available SSH library context and
forward-planning for session replay (phase 2.3).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

PLAN.md

@@ -77,13 +77,34 @@ Goal: A working SSH honeypot that logs attempts, stores them in SQLite, and can
 ### 1.4 Shell Interface & Registry
 - Shell interface definition
 - Registry with weighted random selection
-- Shells receive a configuration struct with common settings from the config file: hostname, banner/MOTD, fake username, and any shell-specific options
 - Basic bash-like shell:
   - Prompt that looks like `user@hostname:~$`
   - Handful of commands: `ls`, `cd`, `cat`, `pwd`, `whoami`, `uname`, `id`, `exit`
   - Fake filesystem with a few interesting-looking files
   - Log all input/output to the session_logs table
 
+#### Session Context
+Shells receive a `SessionContext` struct instead of just `ssh.Channel`, providing:
+- `SessionID` (storage UUID)
+- `Username` (authenticated user, from `ssh.ConnMetadata`)
+- `RemoteAddr` (client IP, from `ssh.ConnMetadata`)
+- `ClientVersion` (SSH client version string)
+- `Store` (for session logging)
+
+This lets shells build realistic prompts (`username@hostname:~$`) and log activity without needing direct access to the SSH connection.
+
+#### Shell Configuration
+- Define a `ShellConfig` sub-struct in the config with common fields: hostname, banner/MOTD, fake username
+- Per-shell overrides via `map[string]map[string]any` (e.g. `[shell.bash]`, `[shell.cisco]`) so each Phase 3 shell can have its own knobs
+- Shells receive the relevant config section, not the entire project config — keeps a clean boundary
+
+#### Transparent I/O Recording (designed for 2.3 Session Replay)
+- Wrap `ssh.Channel` in a `RecordingChannel` before passing it to the shell
+- `RecordingChannel` intercepts every `Read` (client input) and `Write` (server output), logging raw byte chunks with precise timestamps to storage
+- Shells don't need to know about recording — they just read/write normally
+- This ensures consistent, complete capture regardless of shell implementation, and avoids needing to refactor shells when session replay is added in Phase 2.3
+- The current `session_logs` schema (input/output text pairs) may need a companion `session_keystrokes` table with `(session_id, timestamp, direction, data)` for byte-level replay fidelity — evaluate when implementing
+
 ### 1.5 Minimal Web UI
 - Embedded static assets (Go embed)
 - Dashboard: total attempts, attempts over time, unique IPs