API & MCP

Bigbounce paper-orchestration state lives in Convex. The bigbounce-mcp server exposes 11 tools any MCP-aware agent (Claude Code, Codex, Cursor) can call to read or mutate that state — no more hand-editing the 10+ unsynced surfaces this project used to maintain. See DATA_MODEL_ARCHITECTURE.md for the full rebuild plan.

Convex schema

7 paper-orchestration tables in convex/schema.ts (alongside the existing 9 object-level tables for galaxies, MCMC, etc.):

Table	Purpose
papers	Canonical per-paper state (NOT readiness — that's computed)
paper_versions	Append-only .tex version history
r_rounds	Cross-vendor peer-review rounds
findings	Individual R-round findings with truth-audit lifecycle
pathc_caveats	Paper-internal §pathc_caveats deferrals
pods	RunPod lifecycle + cost accounting
tasks	Open work queue (cross-paper + infrastructure)

The load-bearing query is papers.getPaperState(slug) — it computes readiness as ceiling − 2·openBlockers − 1·openMajors − 0.2·openMinors − 1·openCaveats. The ceiling is the evidence-backed readinessCap. The retained package records are P1A 95, P1B 95, P2 95, P3 95, P4 95, and P5 95 (average 95%). They are not six equal submission targets: P2 and P4 are lead scientific results; P1A is a focused Note; P1B is research software; P5 is a standalone companion; and P3 is an integrated supporting data release for the anomaly flagship being rebuilt. Automated-model verdicts and final-hash audits are evidence, not journal acceptance or a replacement for the role-aware author decision and venue-specific checks.

MCP tool catalog

Wire into Claude Code via bigbounce/.claude/mcp_servers.json with CONVEX_URL env var. See mcp/bigbounce-mcp/README.md for install / build steps.

bigbounce_list_papers

Cross-paper dashboard with computed-readiness state. Read-only. The canonical 'where are we?' query.

input: (none)

returns: Array<{ slug, number, shortTitle, status, currentVersion, lastUpdated, readinessComputed, openBlockers, openMajors, openMinors, openCaveats, houstonSignOff }>

bigbounce_get_paper

Full state for one paper by slug. Includes version history + R-round count + caveat counts + computed readiness.

input: { slug: string }

returns: Paper state object (full)

bigbounce_list_open_findings

R-round work queue. Open findings (closureStatus = open | in-progress), optionally filtered by paper.

input: { paperSlug?: string }

returns: Array<Finding>

bigbounce_truth_audit_finding

Apply truth-audit verdict to a finding (REQUIRED before close per feedback_peer_review_truth_audit_protocol).

input: { findingId: string, verdict: VERIFIED|FALSIFIED|STALE|OUT-OF-SCOPE|OPINION, evidence: string }

returns: void (mutation)

bigbounce_close_finding

Atomic finding closure. Enforces closureStatus enum + truth-audit-first ordering.

input: { findingId: string, closureStatus: enum, closureCommit?: string, closureArtifact?: string, closureNote?: string }

returns: void (mutation)

bigbounce_bump_paper_version

Atomic .tex version bump. Site re-renders on Convex subscription — eliminates the 5-file hand-edit drift.

input: { paperSlug, version, datestamp, texCommit, pdfMd5, pdfPages, pdfSizeBytes, changelog, arxivTarballPath?, arxivTarballSizeBytes? }

returns: Id<paper_versions>

bigbounce_list_pathc_caveats

Per-paper §pathc_caveats deferral list. Each item has closureMethod enum.

input: { paperSlug: string }

returns: Array<PathcCaveat>

bigbounce_close_pathc_caveat

Close a §pathc_caveats item. closureMethod enum includes ⚠️ 'text-only-no-real-action' as explicit flag.

input: { paperSlug, label, closureMethod: enum, closureArtifact?, closureCommit?, closureNote? }

returns: void (mutation)

bigbounce_list_pods

RunPod state synced from Convex. Includes cost accounting + backup-location tracking.

input: { statusFilter?: 'running'|'exited'|'terminated' }

returns: Array<Pod>

bigbounce_get_external_review_prompt

Dynamic copy/paste external-review prompt — replaces hardcoded focusAreas array in [slug]/page.tsx.

input: { slug: string }

returns: { paperSlug, paperVersion, pdfPath, prompt }

bigbounce_list_tasks

Cross-paper + per-paper open task queue.

input: { status?, owner?, paperSlug? }

returns: Array<Task>

Skill package

5 Convex-backed slash commands at bigbounce/.claude/skills/ auto-loaded by Claude Code per-project:

/bigbounce-status — dashboard
/bigbounce-r-round <paper-slug> — fire direct-vendor R-round, write findings to Convex
/bigbounce-truth-audit <findingId> <verdict> <evidence> — REQUIRED before close
/bigbounce-close — atomic finding/caveat closure
/bigbounce-bump <paper-slug> <version> — atomic version bump, site re-renders

Anti-pattern guards

Lessons learned (encoded in the MCP layer so no future fire can regress):

No caveat-as-closure. closeFinding + closePathcCaveat require an explicit closureMethod enum. The value text-only-no-real-actionis permitted but raises a ⚠️ flag (Houston 2026-05-29: “simply disclosing deferred items and caveats IS NOT REAL SCIENCE”).
Truth-audit before close. Findings must have truthAuditVerdict set before close succeeds (per feedback_peer_review_truth_audit_protocol).
Provider routes are explicit and auditable. OpenAI-family review uses subscription-backed Codex/ChatGPT CLI sessions, never the OpenAI API. Direct Gemini and Grok API legs retain sanitized raw receipts. Anthropic is not part of the active review route. Provider failures remain failures rather than being silently replaced or relabeled.
No hand-set readiness. readinessComputed is derived from open findings + caveats. Cannot be patched directly via mutation.