From 9377c55414bd9e316fd381fec9d28b894d274f23 Mon Sep 17 00:00:00 2001 From: Jonathan Kirkwood Date: Mon, 10 Aug 2026 07:40:10 -0500 Subject: [PATCH] Add AGENTS.md agent orientation with verified current state --- AGENTS.md | 29 +++++++++++++++++++++++++++++ CLAUDE.md | 1 + 2 files changed, 30 insertions(+) create mode 100644 AGENTS.md create mode 120000 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..40baf52 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,29 @@ +# Boardroom Map + +StartOS s9pk: local-LLM board-deck grader. Decks dropped in `/data/inbox//` 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. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file