boardroom-map/AGENTS.md

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.