# Boardroom Map

StartOS s9pk: local-LLM board-deck grader. Decks dropped in `/data/inbox/<company-slug>/` are graded against the BDEF v1.1 framework by a panel of gemma4-31B containers on the DGX Sparks; a per-company JSON ledger keeps the running tally. Sibling of chambers (same control-plane pattern: GPU-free orchestrator on StartOS drives the Sparks over SSH, wave-based vLLM serving behind a LiteLLM proxy). Origin: gitea.ten31.ai/Ten31AI/boardroom-map.

Global preferences: `~/.claude/CLAUDE.md`.

## Design invariants

- **LLMs never emit numbers.** Scoring is deterministic in scoring.py: composite 0-100 = quant 60 + qual 40 minus capped red-flag penalties. Pinned targets beat extracted ones.
- JSON reliability = single-shot with a retry ladder (json_schema, guided_json, plain + repair), no tool loop. Extraction invalid = deck fails; one deck's failure never kills the job.
- Deck filenames must carry quarter AND year ("Board Deck - Q4 2025.pdf"); bare "Q4" does not parse.

## Gotchas

- `boardroom-vllm:latest` on the Sparks needs `ENTRYPOINT []` (serving.py passes "vllm serve" as CMD; the base image's entrypoint would double it). Grader image is rebuilt on-Spark by hand; the s9pk's baked copy only matters if the image disappears.
- Airgapped serving needs HF_HUB_OFFLINE/TRANSFORMERS_OFFLINE (the --internal network has no DNS).
- FileHelper paths must be absolute (/media/startos/volumes/main/...); relative paths resolve to an ephemeral cwd and writes vanish. (chambers has the same bug.)
- Sideload can return "early eof" with the file intact; plain retry succeeds. Verify with `package installed-version`. UI has no direct LAN port, reachable only via the StartOS "Launch UI" proxy.
- `preJobStopContainers` (set to "vllm-franklin vllm-gemma4-clerk") stops the resident models at job start and deliberately does NOT restart them; the Gazette's 5am Fleet job re-warms its own (see PhiladelphiaGazette AGENTS.md). GPU is the shared constraint across everything on the Sparks.
- Local dev-run: repo .venv (python3.9 needs eval_type_backport), BM_DATA_DIR at a sample ledger; launch.json in ~/Desktop/ClaudeCode/.claude/.

## Current state

(Verified 2026-08-10: `installed-version` on sandy-paycheck.)

- **Installed on sandy-paycheck: v0.1.10:0**, so v0.1.9's progress reviews are live too. Git HEAD is f13d044 (v0.1.9).
- **The v0.1.10 source is DEPLOYED BUT UNCOMMITTED** (orchestrator/ui_auth.py, orchestrator/app.py, startos/versions/v_0_1_10.ts, index.ts), dashboard-auth work from another session. Committing it is the top priority; until then the running service has no durable source of record.
- Strike is the live test company: 9 decks graded, net composite drop of 11.7 since 2023-Q2, hockey-stick forecasts flagged in all 9.
- Next: commit the v0.1.10 work, exercise the two-Spark path with a real grading job.