docs: setup + dep documentation gaps (SETUP.md / extras matrix / implicit requirements)

[SwiftWing21]

Raised during the 2026-04-19 helix review. Baseline observation: pyproject.toml defines 14 optional extras but README only surfaces [launcher] and [codec]. Users install [all] as the safe default and pull ~2 GB of torch/transformers/headroom-ai because no decision matrix exists.

Gap inventory

1. Missing docs/SETUP.md (or equivalent top-level install guide)

Concrete content to add:

Extras decision matrix (the missing table):

Extra	What it enables	Required when
accel	orjson fast-path	optional perf boost
embeddings	SEMA codec (MiniLM)	semantic retrieval
cpu	spaCy NER at ingest	ingestion.backend = cpu (default!)
mcp	python -m helix_context.mcp_server	Claude Code / MCP host
nli	DeBERTa rerank	[ribosome] backend = deberta
otel	metrics/traces	start-helix-tray.bat sets HELIX_OTEL_ENABLED=1
launcher	helix-launcher + helix-status CLI	tray/supervisor flow
launcher-native	+pywebview	native-window dashboard
launcher-tray	+pystray (LGPL)	canonical daily-driver
ast	tree-sitter parsers	code-aware ingest
scorerift	CD spectroscope bridge	ScoreRift dimensions
codec	headroom-ai	semantic compression + new Headroom tray integration
dev	pytest	contributors
all	~everything	convenience (minus dev + LGPL)

2. Implicit requirements not documented

• [otel] is silently required by the daily driver. start-helix-tray.bat sets HELIX_OTEL_ENABLED=1. Without [otel] installed, the server starts but emits no metrics. No warning at startup.
• spaCy model download (python -m spacy download en_core_web_sm) — needed for the default cpu ingest backend. Not in README. First ingest silently falls back.
• Ollama version + install — mentioned but not linked; no min-version noted. No guidance on http://localhost:11434 being reachable.
• SQLite FTS5 — required; on macOS system SQLite may lack FTS5. Not flagged.
• Headroom first-run model download — ModernBERT ONNX (~200 MB), silent on first use. No note about the latency spike.
• Python 3.14 is in use but pyproject classifies only 3.11/3.12/3.13 — wheels for torch/pystray may drift.

3. Missing top-level docs

• No SETUP.md / INSTALL.md — everything is wedged into README Quick Start (three lines).
• No TROUBLESHOOTING.md — "server won't start", "ollama unreachable", "tray icon missing", "genome.db locked" all require git-log spelunking.
• No .env.example — env vars (HELIX_ORG/HELIX_DEVICE/HELIX_USER/HELIX_AGENT/HELIX_MODEL/HELIX_OTEL_*/HELIX_HEADROOM_*) are scattered across README/bat files.
• No persona walkthrough for the 4-layer attribution despite production-shipped design.
• No uninstall/cleanup (~/.helix/, genomes/, headroom state).
• Phase 2 claims layer (commit bc5cc9f) has zero documentation in README despite being a major new queryable fact surface.
• Headroom dashboard at http://127.0.0.1:8787/dashboard is undocumented — especially now that the tray launches it (commit 9390403).

4. Launch-mode table has a Linux/macOS gap

README §Launch lists ./start-helix-tray.sh as "coming." Linux/macOS users who install [launcher-tray] currently have nothing to run.

Scope suggestion

• New docs/SETUP.md absorbing the matrix + implicit-req list.
• README links to it; keeps current "Quick Start" section compact.
• Small section in README for the new [headroom] config + tray integration.
• Separate docs/TROUBLESHOOTING.md with the five recurring failure modes.
• Linux/macOS launcher parity as a follow-on (non-docs task).

Context:

• Gap review commit: 89125e4 (Gemini file-grain) + bc5cc9f (Phase 2 claims) + 9390403 (Headroom tray integration — this PR's driver).
• Filed from session 2026-04-19. Not blocking — code reviews are green, this is a "make it installable by strangers" task.