feat: add GENOME.md - full codebase analysis of the-door (#673)

GENOME.md

@@ -0,0 +1,124 @@
+# GENOME.md — the-door
+
+> Codebase analysis generated 2026-04-13. Crisis intervention web app — a door that's always open.
+
+## Project Overview
+
+the-door is a single-URL crisis intervention web app. A man at 3am can talk to Timmy. No login. No signup. No tracking. Just a door that's always open.
+
+**Mission**: Stand between a broken man and a machine that would tell him to die.
+
+48 files. Static HTML frontend (<25KB, works on 3G). Python crisis detection backend. Safety-critical — a broken deployment could prevent someone from reaching the 988 Lifeline.
+
+## Architecture
+
+```
+Browser → nginx (SSL) → index.html → /api/* proxy → Hermes Gateway
+                                                        ↓
+                                                  crisis/detect.py
+                                                        ↓
+                                                  988 Lifeline overlay
+```
+
+## Entry Points
+
+- **index.html** — The entire frontend. One file. <25KB. Works on 3G.
+- **system-prompt.txt** — Crisis-aware system prompt for the AI.
+- **deploy/deploy.sh** — Deployment script for VPS.
+- **deploy/playbook.yml** — Ansible playbook for deployment.
+- **crisis/detect.py** — Core crisis detection module (canonical).
+- **crisis_detector.py** — Legacy class API wrapper around detect.py.
+- **crisis_responder.py** — Response formatting for crisis levels.
+
+## Data Flow
+
+```
+User message → browser
+    ↓
+index.html → client-side crisis keyword scan
+    ↓
+/api/chat → Hermes Gateway
+    ↓
+system-prompt.txt → injected into AI system prompt
+    ↓
+crisis/detect.py → 5-tier classification (NONE/LOW/MEDIUM/HIGH/CRITICAL)
+    ↓
+crisis/response.py → appropriate response with 988 Lifeline info
+    ↓
+Response → browser → crisis overlay if HIGH/CRITICAL
+```
+
+## Key Abstractions
+
+### Crisis Detection (crisis/detect.py)
+Canonical detection module. Regex-based keyword matching across 4 tiers:
+- CRITICAL: immediate self-harm risk (single match triggers)
+- HIGH: strong despair signals (single match triggers)
+- MEDIUM: distress signals (requires 2+ indicators)
+- LOW: emotional difficulty (single match)
+
+Design principles:
+- Never computes the value of a human life
+- Never suggests death is a solution
+- Always errs on side of higher risk
+
+### Crisis Profiles (crisis/profiles.py)
+Compassion profiles that shape AI response tone based on crisis level.
+
+### Session Tracker (crisis/session_tracker.py)
+Tracks crisis interactions across sessions. Persistent state for ongoing support.
+
+### Gateway (crisis/gateway.py)
+HTTP gateway for crisis detection API. Endpoints for scanning text and getting responses.
+
+### Offline Fallback (crisis-offline.html, sw.js)
+Service worker caches crisis resources. When network is down, users still see 988 Lifeline info and crisis resources.
+
+## File Types
+
+| Type | Count | Purpose |
+|------|-------|---------|
+| .py | 16 | Crisis detection, response, tests |
+| .html | 4 | Frontend, offline fallback, tests |
+| .yml | 2 | CI workflows |
+| .sh | 2 | Health check, service restart |
+| .md | 5 | Documentation, safety audits |
+
+## Test Coverage
+
+### Existing Tests
+- test_crisis_overlay_focus_trap.py — Accessibility: focus trap in crisis overlay
+- test_dying_detection_deprecation.py — Legacy API deprecation
+- test_false_positive_fixes.py — Crisis detection false positive resistance
+- test_service_worker_offline.py — Offline fallback verification
+- test_session_tracker.py — Session tracking persistence
+- crisis/test_rescue.py — Rescue flow testing
+- crisis/tests.py — Core crisis detection tests
+
+### Coverage Gaps
+- No integration tests for full browser → API → response → overlay flow
+- No tests for system-prompt.txt injection into AI system prompt
+- No load tests (what happens at 1000 concurrent crisis users?)
+- No tests for deploy.sh idempotency
+
+### Critical paths that need tests:
+1. **Full crisis flow**: user message → detection → 988 overlay → response
+2. **Offline fallback**: network down → service worker → cached crisis resources
+3. **Deploy safety**: deploy.sh doesn't break running service
+
+## Security Considerations
+
+- **SAFETY-CRITICAL**: the-door serves users in crisis. Broken deployment could prevent someone from reaching 988 Lifeline.
+- **PR safety**: the-door PRs NEVER auto-merge. Requires-human label on all PRs. (fleet-ops#183)
+- **No authentication by design**: no login, no signup, no tracking. Privacy is a safety feature.
+- **Rate limiting**: deploy/rate-limit.conf prevents abuse while allowing crisis access.
+- **Offline resilience**: service worker ensures crisis resources available even without network.
+- **System prompt is safety boundary**: system-prompt.txt defines the AI's crisis behavior. Changes require human review.
+
+## Design Decisions
+
+- **Single HTML file**: no build step, no framework, no dependencies. Works on 3G. Loads instantly.
+- **Client-side detection first**: browser scans for crisis keywords before sending to server. Instant response for critical cases.
+- **Server-side detection second**: crisis/detect.py provides deeper analysis with tiered classification.
+- **Offline-first for crisis**: service worker caches crisis resources. Network failure doesn't block access to help.
+- **No tracking**: privacy protects vulnerable users. No analytics, no cookies, no login.

docs/issue-41-verification.md

@@ -1,32 +0,0 @@
-# Issue #41 Verification
-
-Status: already implemented on main
-
-Issue:
-- #41 [P3] Service worker: cache crisis resources for offline
-
-Acceptance criteria check:
-1. Passed — offline page includes 988 call button, Crisis Text Line, and grounding techniques
-2. Passed — service worker precaches `crisis-offline.html`
-3. Passed — phone number is clickable via `href="tel:988"`
-4. Passed — navigation timeout + offline fallback support intermittent connections
-
-Evidence:
-- `sw.js` precaches `/crisis-offline.html`
-- `sw.js` contains `NAVIGATION_TIMEOUT_MS` and `AbortController`
-- `crisis-offline.html` contains:
-  - `href="tel:988"`
-  - Crisis Text Line / `741741`
-  - grounding prompts for 5-4-3-2-1
-- `tests/test_service_worker_offline.py` already exists on main and passes
-
-Verification run from fresh main clone:
-- `python3 -m pytest tests/test_service_worker_offline.py -q`
-  - `10 passed`
-
-Prior implementation trail:
-- Issue comment already states the core implementation is complete on main
-- Closed PR #122 documented the already-complete implementation and added the offline guarantees test coverage that is now present on main
-
-Recommendation:
-- Close issue #41 as already implemented on main.