boardroom-map/instructions.md

Boardroom Map

Drop portfolio-company board decks in and have a panel of local LLMs running on your DGX Sparks grade them against the BDEF v1.1 framework (Girdley + Munger/Buffett). A deterministic scorer turns the panel's grades into a 0–100 composite and appends it to each company's running scorecard ledger; the web dashboard shows the trends. There is no frontier model and no cloud key — in the default air-gapped mode your confidential decks never leave your hardware.

Boardroom Map is a control plane: nothing serves or runs on your StartOS box (it only SSHes to the Sparks and extracts deck text on CPU).

Setup (run the Actions in order)

1. Configure Sparks — SSH host/user/key for your head Spark (and optionally a second), plus the work directory and image tags. Then Test Spark Connection.
2. Configure Models — the catalog of local models to serve (alias → HF id → which Spark → port), and serving knobs. For air-gapped runs every model must be on the head Spark and present in its HF cache.
3. Configure Graders — the panel: one entry per grader, each a model + a persona (the lens it grades through — e.g. a Munger inversion skeptic, a Girdley operator, a skeptical CFO) + an optional temperature.
4. Configure Grading — the BDEF rubric override (empty = the built-in BDEF v1.1), the Network Mode (air-gapped vs local-services), the extractor + adjudicator models, deck retention, and the scoring weights.
5. Configure Companies — one entry per portfolio company: its inbox slug, display name, KPI aliases, and pinned KPI targets. Pin the profitability thresholds especially — profitability carries the heaviest weight.

Grading decks

1. Drop each company's deck into its inbox folder, e.g. inbox/acme-widgets/2026-Q2-deck.pdf (PDF / DOCX / TXT / MD), via the Web UI or the service's inbox directory.
2. Run Grade Decks (or enable auto-grade on drop).
3. Watch the activity log. The service extracts text locally, serves the needed models on the Sparks in waves (so a panel can span more models than fit in GPU memory at once), runs the structured KPI extractor, then each grader, then the adjudicator, and finally computes the composite and updates the company's ledger. Read the results on the dashboard or via View Latest Scorecard.

How the score works

The composite is 0–100 = quantitative 60 + qualitative 40 − red flags (max 15):

• Quant 60 — profitability KPI attainment 30 (the heaviest single slice), other measurable KPIs 20, and forecast integrity 10: deck N's actuals are chained against what deck N−1 promised, so sandbagging and quietly moved goalposts cost points.
• Qual 40 — eight BDEF categories (A–H), up to 5 points each, scored by the panel with evidence quotes (thin evidence scales the score down).
• Red flags — up to −15; silently dropped KPIs are flagged automatically, and flags raised by only one grader are damped.

Pinned targets from Configure Companies are graded every quarter whether or not the deck mentions them — a deck cannot improve its score by going quiet.

Network modes

• Air-gapped (default): grader containers join an --internal Docker network — they can reach only the on-Spark model proxy, with zero internet egress. Models are served from a pre-pulled HF cache. All models must be on the head Spark. Strongest confidentiality.
• Local services: graders may also reach LAN services (e.g. SearXNG) and the second Spark. This network has egress unless you firewall it — use only when you accept that graders can reach the network.

The original decks are extracted to plain text on the StartOS box; only that text is shipped to the Sparks, and it is wiped from the Sparks after the job (the scorecards and ledgers are kept on your StartOS box).