This is the reference half of onboarding. If you are looking for where to start — the four routes, the six pipeline stages, what the platform can and cannot support, and your first task — that is the onboarding overview, and it takes about six minutes. This page is what you read once you know which part you need.

Part I is numbered on its own 00–18 scale, so a cross-reference like “see 08 Pipeline” means section 08 of this part. Every number here carries the database it was measured on and the date; re-measure before quoting. The other four parts, with their section counts and read times, are listed at the foot of this page.

Repo documents, in reading order

docs/onboarding/README.md is the ordered index: QUICKSTART, infra-access-r2-staging-prod, paper-pipeline, categorization-and-ontology, acquiring-recent-papers, streamlined-corpus-run, extractor-contract-and-gaps, the 2026-07-19–24 handoff, and CORPUS-DIAGNOSIS. Then docs/extraction/extractor-contract-and-gaps.md, docs/AGENT_HANDOFF.md, docs/PLATFORM_STATE.md, docs/TECH_STACK.md, docs/QUICKSTART.md, docs/multi-zone-deployment.md, CLAUDE.md.

Read this first if the science is new to you. A microbial electrochemical system (MES), also called a bioelectrochemical system, uses the electrochemical activity of living microorganisms to interconvert chemical and electrical energy, or to drive synthesis. Every device in the taxonomy is a variation on one cell; what changes is the reaction you drive and the product you harvest. The full treatment is on /learn/science; the two diagrams below are the pair everything later in this page assumes.

The reference device

In the canonical case — a microbial fuel cell — electroactive bacteria colonise an anode and oxidise an organic substrate such as acetate or the organic load of wastewater. Oxidation releases electrons, which the bacteria deposit onto the electrode instead of onto a soluble acceptor. Those electrons travel through an external circuit to a cathode, where they reduce a terminal acceptor, often oxygen. The electron flow is a usable current; the proton flow that balances it closes the circuit through the electrolyte.

The public methodology page, section by section

Everything on messai.io/learn/science is carried here, so either page answers the question and neither is the only copy. That page is the outward-facing account and is depth-layered behind “Read the full method” panels; this one adds what was measured internally, and says where the two disagree. Use whichever you are already in.

Sibling pages that page links out to, not duplicated here: System types, Sustainability, History of MES, the proof dashboard (live database counts and training artifacts per request) and the whitepaper — the strategic why, where the science page and this Atlas are the technical how.

The four public claims, and where each one is tested here

The proof numbers, as published: 23,568+ curated papers, 195,846 extracted value rows, 2,812 parameter-graph edges, and 97.98% out-of-sample interval coverage on MFC + MEC, with an honest-gaps section naming what is thin or unvalidated. Two of those need the footnote this Atlas adds: the coverage figure was computed on a split that 14 shows is separable at AUC 0.77–0.92, and the corpus counts are dated snapshots that differ slightly from the staging measurements below. Open data: the curated packages are public — canonical microbes, electrode materials with DFT-derived properties, the parameter ontology, and a catalog of external datasets — each shipping a SCIENTIFIC_INTEGRITY.md of known caveats, with large blobs mirrored to Hugging Face. Details in 07.

also public  Live version: messai.io/learn/science → System taxonomy.

The canonical taxonomy (version 2) is 17 primary system types — 14 real devices plus 3 meta classes — with 12 combination types, multi-axis subtypes, an 11-value study-focus axis and 8 application domains, all routed for prediction through 5 physics families. It is the authoritative classifier that the extraction pipeline, the ML predictors and the UI all share; the enum lives in apps/web/src/lib/taxonomy/system-types.ts. Section 09 measures how much of the corpus actually carries each value.

Why the family, not the device, is the unit of prediction

Restricting the world to MFC / MEC / MDC — as most tools do — silently coerces desalination, metal-recovery, synthesis and sensing systems into fuel-cell-shaped output. The right abstraction is the physics family: the group whose transport and reaction physics actually govern the outcome. Predictions route to a family; subtypes become features, combinations become coupling rules. The rationale is statistical: branching on all 17 types would train rare classes on a handful of papers each and return noise.

The full device roster

Three meta classes complete the 17: REVIEW (review / meta-analysis), FUNDAMENTAL (mechanistic electron-transfer studies) and OTHER (genuinely novel architectures). They are tracked so the predictor never mistakes a review’s cited numbers for fresh measurements — the same reason 26.3% of values sourced from references is a headline finding in 15 July 2026 agents. Abiotic fuel cells (PEM, SOFC, PAFC) are a separate taxonomy: the predictor stack has tuned physics for them, but they are not bioelectrochemical and are kept out of the BES classifier so a proton-exchange-membrane paper never contaminates the microbial priors.

Subtypes: orthogonal axes, not one flat list

Subtypes are stored as an object of orthogonal axes because a token like acetate means something different for a synthesis product than for a substrate. Each primary type populates the axes that make sense for it.

Combinations: coupling rules, not new predictors

Real reactors are often two systems at once. Rather than train a separate model per combination — which would be starved of data — each is treated as a coupling rule over the base families. The best-studied combinations carry their own variants: CW_MFC splits into horizontal_subsurface_flow, vertical_flow and floating.

Two orthogonal axes: study focus and application domain

The primary type says what reactor a paper is about. Two further axes say what kind of study it is and what it is for, so a query can ask “which MFC papers are about new anode materials for wastewater?” without full-text search.

also public  Live version: messai.io/learn/science → Thermodynamics + Electrode kinetics.

What a cell can do is bounded by thermodynamics; what it actually does is set by kinetics and losses. Thermodynamics gives the ceiling, and the ceiling is the gap between the two half-reaction potentials.

The redox ladder

Each half-reaction has a standard potential on the standard-hydrogen-electrode (SHE) scale, shifted for real concentrations by Nernst. The cathode couple sits high, the anode couple sits low, and the vertical gap between them is the theoretical cell voltage. Swap the cathode couple and you have a different device.

An air cathode (O₂/H₂O, +0.82 V) against an acetate-oxidising anode (≈ −0.28 V) gives E°cell ≈ 1.1 V. Real cells deliver 0.3–0.8 V after losses.

Where the 1.1 V goes — the loss cascade

Kinetics: Butler–Volmer and Tafel

Kinetics turns a thermodynamic possibility into a rate. The governing relationship between overpotential and current density is the Butler–Volmer equation, with the biofilm acting as the anode’s catalyst layer.

The exchange current density j₀ captures how intrinsically fast the electrode reaction is at equilibrium; the transfer coefficient α sets how symmetric the anodic and cathodic branches are; and the Tafel slope — the straight-line region on a log-current plot — is what most papers actually report, from which α can be back-fitted. A good bio-anode has a high j₀: the reaction turns on for less overpotential, so more voltage reaches the load. Every millivolt of η is voltage you do not deliver.

The polarisation curve, and the four levers

Sweeping the load traces voltage against current. The three regions map one-to-one onto the three losses — activation (the steep initial drop), ohmic (the linear middle), mass transport (the final collapse) — and the power curve peaks where the external load matches the internal resistance. That peak, not the open-circuit voltage, is what a design is optimised toward, which is why extracting a single quoted “maximum power density” without its derivation method is lossy (see the derivation_method field in 12 Corpus run).

Reactant must diffuse across a thin diffusion layer to reach the electrode. Push the current higher and the surface concentration falls; when it reaches zero the current is diffusion-limited and cannot rise further, no matter the voltage. That is the collapse at the right of the curve, and the limiting current.

Internal resistance is often the single largest lever on power: the sum of ohmic resistance (electrolyte, membrane, electrode spacing) and the charge-transfer resistances of both electrodes. By the maximum-power-transfer theorem, power delivered to the load is maximised when the external resistance matches the internal resistance — which is why it is one of the parameters the knowledge graph links to power with a causal edge.

Impedance (EIS). Electrochemical impedance spectroscopy applies a small AC perturbation across a frequency range and fits the Nyquist spectrum to an equivalent circuit — typically a Randles circuit — separating losses a single DC polarisation curve blends together: Rs solution resistance (the high-frequency intercept, the ohmic term), Rct charge-transfer resistance (the semicircle diameter, inversely related to j₀), Cdl double-layer capacitance, and the Warburg low-frequency diffusion tail. EIS spectra are Tier C on the extraction roadmap (12 Corpus run) — the schema does not capture them today.

also public  Live version: messai.io/learn/science → Biofilm & EET.

The defining trick of MES is extracellular electron transfer (EET): electroactive bacteria route respiratory electrons onto a solid electrode instead of a soluble acceptor. Understanding EET is understanding the anode.

The four routes are usually mixed in one biofilm, which is why by_mechanism (direct_ET_cytochrome, direct_ET_nanowire, mediated_endogenous, mediated_exogenous, interspecies_ET) is a subtype axis on FUNDAMENTAL papers rather than a device class.

The model organisms

The mess-microbes package (07 Platform map) is the curated catalog behind this: 28 microbes, plus 181 MicrobeKineticConstant rows.

Growth kinetics — Monod

Uptake is proportional to concentration when substrate is scarce and flattens to a maximum when it is abundant. K_s is substrate-specific, which is why substrate identity is kept as a canonical feature rather than pooling glucose and acetate kinetics together — and why substrate being the worst-linked input in the corpus (0.7% coupled, see 12) is a modelling problem, not a cosmetic one. On 2026-09-08 the identity μ_max = ln 2 / doubling time validated three values the paid LLM verifier had rejected: a free invariant beating a paid check.

also public  Live version: messai.io/learn/science → Performance metrics.

MES performance is reported through a compact set of metrics, but with inconsistent normalisation across the literature. Knowing exactly what a number is normalised to is the difference between a fair comparison and a meaningless one.

Always read the interval, the system class and the normalisation before comparing two numbers. Section 09 is how a raw name becomes a canonical slug and an SI value; section 14 is what happens when you try to predict these metrics across papers.

Staging and prod share the same Supabase pooler host in eu-central-1, so a hostname check proves nothing. Every remote write in scripts/ passes through resolveDbTarget(), which pins staging to its project ref and demands --expect-ref for prod. Promotion is one direction, additive, schema before data.

Day-one checklist

Part III is the platform map  The measured platform — zones, schema, pipeline, 3D, P&ID, open source, gaps — lives once, in the Platform map tab. This section only opens the interactive model so it is one click from the atlas.

Architecture: one model, eight UML views

Eight UML 2 views over one model of the whole platform. C1 is the altitude everything else hangs from: three kinds of actor, four Vercel zones, the shared packages, the state layer and the external systems. Every box with a ＋ corner opens its own diagram — the four zones, the package graph, the persistence model and the corpus pipeline — and Esc comes back up. Structural counts were measured against this repository on 2026-09-09; corpus and science numbers deliberately stay out of the diagram and live in the dated tiles.

Every surface MESSAI ships is supposed to be built from @messai/ui and the Tailwind preset next to it. Most are. This section is the inventory a newcomer builds against — what exists, which generation is live, the rules that are not negotiable, and the measured distance between the rule and the tree. Counted against development on 2026-09-11; re-measure before quoting. Two things have moved since that count: the stock-colour rule became a lint ratchet (2026-09-12), and the palette became warm monochrome (2026-10-05) — both noted below.

The three hard rules

What exists, by tier

The catalogue is drawn, not just listed: /design-system renders live token swatches and component examples, and /dev/v3 is the v3 proving page.

Three generations coexist, and only one is live

This is the thing to understand before adding a component, because the obvious guess is wrong twice.

Where the site is inconsistent today

Adding or changing a component

Every scraper, downloader, resolver and parser that built the corpus, surveyed 2026-09-07. Two download lineages coexist: lineage A walks a 9-provider chain per paper (download_from_db.py); lineage B runs tiered batch passes built to defeat the ~11k publisher 403s (scripts/acquisition/). Free and official providers only, never Sci-Hub or LibGen. Full per-file table with status and dates: docs/onboarding/acquisition-tooling-inventory.md; visual companion: the Scraper Atlas.

Text extraction went through three generations

Nougat (2025) → marker (April 2026) → reading BioC-PMC XML directly (May 2026). The XML path keeps tables intact and yields about 10% more values while skipping OCR entirely. Marker replaced Nougat because it handles tables and multi-column layout better and runs roughly ten times faster, and it pulls from R2 on a cache miss. Value extraction downstream is the separate v2 extractor. The whole 2025 Nougat stack — batch runner, FastAPI queue server, URL extractor, “research-grade” variant, PyMuPDF fallback, plus five TypeScript clients — is superseded or dead but still in the tree, with run_extraction.sh still wired to pnpm nougat:*. Do not restart from it.

Two cautions that cost time. papers/staging/resolution.jsonl is dated 2026-04-29, so DOI matches will miss and stubs named Local PDF <sha8> will be proposed — fix the SHA→DOI map before accepting them into a 23k-row corpus. And marker-quality text is patent-only today: 22 marker text files exist on disk against 1,375 values_v2.json artifacts, so everything else is PyMuPDF output.

also Part II  This is the Atlas's own summary of a corpus pass. Part II is the runbook itself, stage by stage, with the today-vs-target command pairs: 01 State · 02 Fix first · 03 The run · 04 Ontology duties · 05 Extraction schema · 06 Beyond · 07 Coupling.

Every layer of the corpus pipeline already has a working component. Each one is either not wired to anything, never run, or broken by a small bug. Nothing here needs to be built from scratch; the work is to connect what exists and run it in dependency order, with a measured gate at each step. Grading a paper as complete tells you almost nothing about whether any single experiment inside it can be modeled.

The interactive pipeline map and every stage in detail are in Part II · 00 Pipeline map, under the next tab.

The sequence, and why the order is not optional

The order is not optional because a large extraction run on the current backfill reproduces the 24,540 orphaned condition sets of the 807-paper run at ten times the scale.

The extractor of record

Backlog is the 8,743 legacy papers whose rows carry no inline conditions; no backfill can ever couple them, so they must be re-extracted. Decided 2026-09-10 (PR #902): arm B — v2’s flat transport with the v1.2 sub-prompt families ported onto it as separate flat calls — run recency-first so 2025–26 lands before the backlog. Measured on a 20-paper slice: 95% precision [92–98], 62% modelable, $0.05 per paper, and 0 of 109 values sourced from other papers’ reference lists, where v2’s current prompt sourced 99 of 214. The three-pass variant, CMA v3 for bulk and the v1.2 orchestrator are decision history, not options. One caveat could reverse it: the gold set is LLM-adjudicated, not human-verified.

Coupling: the one-line version

41,080 ConditionSet rows describe only 9,720 real (paperId, label) tuples, and 27,419 sets have no linked output at all (staging, 2026-09-08). The backfill re-mints a fresh generation on every run because the unique key names a runId it never sets. The approved fix, in order: collapse the duplicates, add @@unique([paperId, label]), then reuse an existing set at sync time instead of creating one — about 4 h, mutates staging, so it needs a stated go. Setting runId was considered and rejected: it makes each re-run legitimately distinct, which is the behaviour being stopped.

The measured table, the coupling diagram, the five-step fix table and both root causes with their file and line numbers are in Part II · 07 Coupling.

Two systems share the word “experiment”

The platform is really about one thing: a complete experiment record — a design, a full set of conditions, and a co-measured outcome — not a paper. But the schema holds two separate systems under that name, and conflating them is the fastest way to misread this section. The corpus-derived half is ConditionSet plus ExtractedParameterData, everything measured above: one row per condition a paper reports, extracted at scale, coupled by conditionSetId. The user-authored half is Experiment, Run, and Measurement — a personal lab notebook for a signed-in researcher, entirely unrelated to paper extraction, with no shared code path. Everything above this point in this section is the first system.

The shape of that coupling — one paper, many condition sets, each carrying zero or more extracted values — is drawn once, in Part II · 07 Coupling.

The user-facing surfaces: real, but a different feature and hard to find

apps/web/src/app/[lang]/experiments/[id]/page.tsx and apps/web/src/app/[lang]/runs/[id]/page.tsx are genuine server components — they call prisma.experiment.findUnique / prisma.run.findUnique directly, with force-dynamic, and render real rows, not mocked data. But they read the user-authored trio above, not ConditionSet. There is no listing page for either route, and the only inbound link anywhere in apps/web/src is one card on /projects/[id], which itself requires a signed-in session scoped to that user's own projects. There is no page anywhere in apps/web that lets a visitor browse the corpus's coupled experiment records — that story lives only in coupling-completeness.ts script output and the onboarding docs.

The corpus-wide coupling story on this page — 1,760 complete records, the two bugs above, the class-median result at 14 — has no dedicated UI at all today.

The priors turn a pile of comparable measurements into a defensible expectation with honest uncertainty. They are hierarchical, fitted on the log scale, and sampled with NUTS. A prediction is not a prior look-up: it routes to a physics family, draws the base estimate from the hierarchical prior, then passes through a calibration layer.

Power density, current density and resistance are log-distributed across orders of magnitude, so their arithmetic mean is dominated by a few large values and is not a sensible estimate. The earlier v0 approach — analytic method-of-moments — was retired in May 2026 as mathematically wrong for these metrics, not merely imprecise. Everything is now fitted on the log scale.

Partial pooling: sparse classes borrow strength

A shared hyper-prior sits above every system-type estimate. Classes with abundant data stay close to their own evidence; sparse classes are shrunk toward the global expectation rather than over-fitting three noisy points, and the amount of shrinkage is learned from the data, never assumed. Full pooling would erase real between-class differences — an MFC and an MEC are not the same device. No pooling would hand each sparse class a model built on too little data to trust. The hierarchy interpolates by the evidence, so priors degrade gracefully on rare classes instead of returning confident nonsense.

The three prediction steps

Treat a prediction as a prior to be updated by your own data, not as ground truth. For a novel design the interval will often span an order of magnitude — and given a corpus CoV near 1,285%, anything narrower would be dishonest. Stated limitations from the public page, worth carrying here: extraction success is not currently measured; the Gemini fallback over-assigns OTHER (about 52% versus about 14% on Haiku); holdout validation covers MFC + MEC only; canonical mapping sits near 51.6% on that page’s count against 45% measured on staging 2026-09-07 (08); the physics layer is a 0-D mean function and the calibration is plain split-conformal.

Measured 2026-09-02 on the local corpus, read-only, branch feat/bes-benchmark-v1 (not merged into development or main as of 2026-09-08; the package lives at services/ml-engine/training/benchmark/ on that branch only). The first paper-disjoint, leakage-audited held-out set for BES performance prediction. The result is a clean negative. Markdown port: docs/onboarding/held-out-benchmark.md; visual companion: the bes-benchmark-v1 artifact.

3,593 rows from 590 papers after eight recorded filters (7,336 → 6,884 vintage v2/curated → 6,466 verifier not failed → 5,338 not cited from another paper → 5,281 no physics/dedupe flags → 5,023 BES not review → 4,965 physical bounds → 3,593 exact duplicates removed). Three splits pass the paper-level adversarial audit (hash 0.46–0.53, group 5-fold 0.41–0.62, temporal ≥2024 0.43–0.58); the stored fit_validation_role split leaks on every target (0.77–0.92). Between-paper spread is roughly twice within-paper, so there is explainable variance; the covariates the corpus holds (temperature 49%, pH 44%, anode material 74%, HRT 6%, inoculum 0%) do not explain it.

Since 2026-09-02 on the same branch: a within-study contrast census (2026-09-07, staging, read-only) found 18 factor × outcome pairs clearing 10 papers; continuous vs batch operation raises current density ~0.47 dex and power ~0.40 dex in 80–83% of papers, and raising R_ext lowers current density in 8 of 9 papers — the physics direction cross-paper models never recovered. Do not conflate with the separate cohort benchmark export (scripts/derived/build-benchmark-export.ts, regenerated as schema 2.0 from staging in PR #862 on 2026-09-08), which feeds /methodology#schema.

Three Claude Managed Agents ran for the first time, then at corpus scale. Each proved from its own direction that the platform's problems sat upstream of everything being tuned. Click any dot for the detail; bold-ringed dots are the ones to know.

8 Sept 2026 to 27 Aug 2027, in three phases and eighteen workstreams, each with dated deliverables. The roadmap is organised around one first-of-a-kind brewery installation; every other pillar either feeds it or funds it.

Open the full page for the interactive version and every detail.

Two dates are hard. The Villano meeting, with the ISMET president, sits at roughly 15 Oct 2026. The P1 gate, a funding event or two paid studies, falls on 19 Dec 2026.

Six pillars, eighteen workstreams

Where this connects: 12 Corpus run above is workstream B1's ground truth. Its measured coupling and acquisition state is what B1's milestones are scheduled against.

Two views of the same backlog. The first is by area, drawn from the onboarding docs; the second is the platform’s own P0 to P2 ranking — P0 blocks the corpus machine, P1 bounds what can be modeled or served, P2 is hygiene. Both are dated. Nothing here is a wish list: every row names what unblocks it.

The backlog, ranked

One register. P0 blocks the corpus machine, P1 bounds what can be modelled or served, P2 is hygiene; rows marked — are known gaps that have not been ranked against the others yet.

Science terms are as defined on messai.io/learn/science; platform terms are as used in the repo. Where a term means two things, both senses are given — that ambiguity has cost time before.

BES

Bioelectrochemical system — the umbrella term for any device where microbes (or enzymes) catalyse redox reactions at electrodes wired to an external circuit.

MES

Two senses. As an umbrella: microbial electrochemical system, the whole field. In the extraction schema and primarySystemType: Microbial Electrosynthesis, cathodic CO₂ reduction — one of the 14 devices.

EET

Extracellular electron transfer — how bacteria move respiratory electrons onto an electrode, by direct contact, conductive nanowires, or soluble mediators.

DIET

Direct interspecies electron transfer — electrons passed directly between species through pili or conductive minerals; the basis of syntrophy and electromethanogenesis.

Anode / cathode

The oxidising electrode, where the biofilm gives up electrons, and the reducing electrode, where they are consumed.

Overpotential (η)

Voltage beyond the thermodynamic minimum needed to drive an electrode reaction at a useful rate. Split into activation, ohmic and concentration terms.

Exchange current density (j₀)

How intrinsically fast an electrode reaction runs at equilibrium — higher is better.

Tafel slope

The slope of overpotential against log-current in the kinetically-limited region; encodes the transfer coefficient.

Limiting current

The maximum current a diffusion-limited reaction can sustain, reached when surface reactant concentration falls to zero.

Coulombic efficiency

Fraction of the electrons available in the substrate that are actually recovered as current. Bounded 0–100% and diagnostic of electron leakage.

Power density

Power normalised to electrode area (areal, mW/m²) or reactor volume (volumetric, W/m³). Keep the two apart — they are separate canonical kinds.

Monod kinetics

Saturating relationship between substrate concentration and microbial growth or uptake rate, set by μ_max and the half-saturation constant K_s.

EIS / Randles circuit

Electrochemical impedance spectroscopy, and the equivalent-circuit fit that separates solution resistance, charge-transfer resistance, capacitance and diffusion.

Physics family

One of 5 groupings — anodic oxidation, cathodic reduction, ion transport, selective reduction, sensor/photo — that predictions route through. A calibration and out-of-distribution stratum, not a predictor.

Canonical slug

The normalised identity a free-text parameter name is mapped onto so values from different papers can be compared and pooled. Layer 2 of the five-layer value ontology (09).

Kind

Layer 3: the SI quantity a slug belongs to (SLUG_TO_KIND). A slug outside it is never SI-normalised and never modelable. This, not the category, is the modelable gate.

ConditionSet

The within-paper coupling record that binds an outcome to the operating point it was measured under. Without it a number has no context.

Experiment record

The atomic unit for modeling — not the paper. Grading a paper as complete says almost nothing about whether any single experiment inside it can be modeled.

Hierarchical prior

A Bayesian prior that pools information across system types so sparse classes borrow strength from data-rich ones, with the shrinkage learned rather than assumed.

Conformal calibration

A distribution-free method — here, plain split-conformal — that adjusts prediction intervals so stated coverage matches observed coverage on held-out data.

ECE

Expected calibration error — how far stated interval coverage drifts from observed coverage. Lower is better.

CoV

Coefficient of variation, standard deviation over mean. For power density it is ≈ 1,285%, which is why point estimates are meaningless without an interval.

dex

A decade on a log₁₀ scale. A median absolute error of 0.80 dex is a typical miss of about ×6.

Adversarial AUC

The score of a classifier trained to tell a train split from a test split using covariates alone. 0.5 means exchangeable; above 0.65 the split leaks and every metric computed on it is optimistic.

resolveDbTarget()

The only sanctioned way to resolve a remote database, gated on the Supabase project ref rather than the hostname — staging and production share a pooler host, so a hostname check proves nothing.

Physics families vs. system types

17 primary system types (14 devices + 3 meta classes) exist in the taxonomy; predictions route through 5 physics families. Branching on all 17 would train rare classes on a handful of papers each.

Read this first. Every later section details one row of the table below.

The organizing fact. Every layer of the corpus pipeline already has a working component. Each one is either not wired to anything, never run, or broken by a small bug. Nothing here needs to be built from scratch. The work is to connect what exists and run it, in dependency order, with a measured gate at each step.

0a. Five layers, measured on staging 2026-09-08

These are architectural layers — where the machinery lives — not pipeline stages. The six lifecycle stages a paper passes through are acquire → screen → extract → sync → harmonize → promote; each layer below serves one or more of them.

0b. The sequence, and why the order is not optional

Each layer's output is the next one's input. Coupling hygiene comes first because a large extraction run on the current backfill reproduces the 24,540 orphaned sets of the 807-paper run at ten times the scale.

1. Coupling hygiene (§7): collapse the 31,360 duplicate sets, add @@unique([paperId, label]), reuse an existing set instead of creating one. About 4 h. Mutates staging, so it needs a stated go. The runId variant is the rejected fix; §7 says why.
2. Acquisition blockers (§2): the 2.5 h list. Unblocks new papers reaching R2 and staging.
3. Extraction (§3 stage 7, §5): fix the 3-pass extractor's two bugs, then run recency-first on the 1,405 papers from 2025–26, emitting ConditionSet rows at sync time.
4. Vectorize (0f): abstract backfill, then the chunk table.
5. Gates, then automation (§4d, §6): wire coupling-completeness.ts and the fixture recall check as pass/fail, then land the GHA DAG.

0c. What makes it intelligent rather than merely running

Each of these already exists in the repo. None is wired in.

• Gap-driven acquisition. scripts/acquisition/search-gaps-openalex.ts reads gaps[] from within-paper-effects.json and searches for exactly the evidence the models lack.
• Value-of-information ordering. scripts/quality/voi-covariate-priority.ts ranks what to extract next by expected information gain, instead of oldest first.
• Experiment-centric extraction. Pass 1 of the 3-pass extractor enumerates a paper's distinct experimental conditions and emits one ConditionSet per condition with a verbatim snippet. On the two papers where it worked it found 7 and 9 conditions.
• Free invariants before paid verification. On 2026-09-08 the identity μmax = ln 2 / doubling time validated three values the paid LLM verifier had rejected. Run the verifier only where a cheap invariant fails.
• Canonicalize at extraction. Give the extractor the alias index so canonical_slug is proposed during extraction and verified offline, instead of matched afterwards by a script plateaued at 45%.

0d. The one decision that is yours: extraction budget

For the 8,743 legacy papers whose rows carry no inline conditions, no backfill can ever couple them. They must be re-extracted.

Recommendation: the 3-pass for bulk with CMA on a 20-paper benchmark slice, recency-first so 2025–26 lands before the backlog.

0e. Agent onboarding: load these before touching the pipeline

0f. Vectorization, the layer no other section covers

ResearchPaper.abstract_embedding is a pgvector column written by services/ml-engine/training/embed_papers.py (BAAI/bge-large-en-v1.5) and read by apps/api/src/app/api/research/semantic-search/route.ts. On staging 2026-09-08: 13,788 of 23,579 papers carry one, 10,497 of them visible. 13,251 papers have an abstract over 50 characters, so coverage tracks abstract availability and the remaining gap is mostly papers with no abstract to embed.

Section-level chunk vectors are a different story. The open-source pipeline's embed.py writes chunks.jsonl and vectors.npy per paper to disk, and no table in the database holds them, so nothing served can search full text. Closing this is two steps: run the abstract backfill for new cohorts as part of stage 8, then add a chunk table and a promote script so the on-disk vectors become queryable. The corpus-refresh design already calls the abstract backfill the highest-value, lowest-risk first move, because it hardens the RAG layer behind the lab agent with no queue and no new infrastructure.

Written 2026-09-07 from source and from read-only counts on staging (the canonical staging project; ref in docs/staging-access.md). Local Supabase is empty and the local PDF cache is empty; R2 holds the bytes. Re-measure before quoting any number here.

The corpus thins exactly where it should be growing. 2023 has 2,000 papers and 521 PDFs; 2025 has 1,249 and 225.

Do these before the first cohort. Each one removes a manual workaround from §3. The rule for all of them: resolve the database through resolveDbTarget() in scripts/lib/db-target.ts (TypeScript) or add_target_argument() / resolve_or_exit() in scripts/quality/db_target.py (Python), gate on the Supabase project ref rather than the hostname, and make --target staging the default.

Eight runbook steps, not a different pipeline: they are the operational expansion of the six lifecycle stages (acquire → screen → extract → sync → harmonize → promote) named on the onboarding overview. Point the shell at staging once, explicitly, before anything else.

set -a; source .env.local; set +a          # SUPABASE_STAGING_DIRECT_URL, R2_*, AI_GATEWAY_API_KEY, OPENALEX_API_KEY, UNPAYWALL_EMAIL, CROSSREF_MAILTO
export DATABASE_URL="$SUPABASE_STAGING_DIRECT_URL"
export DIRECT_URL="$SUPABASE_STAGING_DIRECT_URL"
export DATABASE_URL_STAGING="$SUPABASE_STAGING_DIRECT_URL"
unset DATABASE_URL_LOCAL                   # db_target.py refuses a non-local value here
export PAPERS_ROOT="$(pwd)/papers"
echo "$DATABASE_URL" | grep -q "$STAGING_REF"   # the staging project ref, from docs/staging-access.md || echo "ABORT: not staging"

papers/.venv/bin/python3 scripts/acquisition/search_openalex_underrepresented.py \
  --since 2025-01-01 --max-per-bucket 100 --min-score 0.5 \
  --output papers/acquisition/openalex-recent-$(date +%F).json
papers/.venv/bin/python3 scripts/acquisition/search_openalex_underrepresented.py \
  --since 2025-01-01 --max-per-bucket 100 --insert-to-db --apply --i-understand-this-mutates-staging

papers/.venv/bin/python3 scripts/acquisition/search_openalex_underrepresented.py \
  --since 2025-01-01 --max-per-bucket 100 --insert-to-db --apply --target staging
pnpm tsx scripts/discover-papers-via-openalex.ts --since=2025-01-01

pnpm tsx scripts/acquisition/ingest_doi_list.ts \
  --input papers/staging/manual-doi-lists/$(date +%F)-recent-bes.jsonl \
  --source-tag recent-bes-$(date +%F) \
  --applies-to-domain wastewater_treatment,resource_recovery \
  --apply --i-understand-this-mutates-staging

pnpm tsx scripts/acquisition/ingest_doi_list.ts \
  --input papers/staging/manual-doi-lists/$(date +%F)-recent-bes.jsonl \
  --source-tag recent-bes-$(date +%F) \
  --applies-to-domain wastewater_treatment,resource_recovery \
  --apply --target staging

papers/.venv/bin/python3 scripts/acquisition/download_paperscraper.py --limit 200
papers/.venv/bin/python3 scripts/acquisition/download_unpaywall.py --source-tag recent-bes-$(date +%F) --limit 200
papers/.venv/bin/python3 scripts/acquisition/download_curl_cffi.py --limit 200

papers/.venv/bin/python3 scripts/acquisition/download_paperscraper.py --limit 200
papers/.venv/bin/python3 scripts/acquisition/download_unpaywall.py --source-tag recent-bes-$(date +%F) --limit 200
papers/.venv/bin/python3 scripts/acquisition/download_curl_cffi.py --limit 200

papers/.venv/bin/python3 scripts/acquisition/promote_to_canonical.py            # dry-run
papers/.venv/bin/python3 scripts/acquisition/promote_to_canonical.py --apply
pnpm tsx scripts/storage/migrate-local-to-r2.ts --limit 250                     # dry-run manifest
pnpm tsx scripts/storage/migrate-local-to-r2.ts --apply
pnpm tsx scripts/extraction/sync-papers-to-db.ts --dry-run --limit 250          # read papers_matched_by_doi and the stub count
pnpm tsx scripts/extraction/sync-papers-to-db.ts --apply --i-understand-this-mutates-staging
pnpm tsx scripts/storage/backfill-r2-keys.ts                                    # dry-run
pnpm tsx scripts/storage/backfill-r2-keys.ts --apply

pnpm papers:hydrate --dry-run                     # only if reprocessing older papers
pnpm papers:hydrate
bash scripts/acquisition/run-pipeline-for-source.sh --tag recent-bes-$(date +%F) --skip-ingest --skip-acquisition

bash scripts/acquisition/run-pipeline-for-source.sh --tag recent-bes-$(date +%F) --skip-ingest --skip-acquisition

pnpm tsx scripts/extraction/classify-title-abstract.ts --limit 200 --apply --i-understand-this-mutates-staging
# optional higher-resolution screen, about $1.02 per 100 on Sonnet
python3 scripts/storage/mint-presigned-urls.py --shas /tmp/new-200.txt --out /tmp/presigned.json
cd docs/corpus-screening-agent && ./launch.sh && ./poll.sh
pnpm tsx scripts/classify-system-taxonomy.ts --apply --limit=200

pnpm tsx scripts/extraction/classify-title-abstract.ts --limit 200 --apply --target staging
# optional higher-resolution screen, about $1.02 per 100 on Sonnet
python3 scripts/storage/mint-presigned-urls.py --shas /tmp/new-200.txt --out /tmp/presigned.json
cd docs/corpus-screening-agent && ./launch.sh && ./poll.sh
pnpm tsx scripts/classify-system-taxonomy.ts --apply --limit=200

pnpm tsx scripts/extraction/phase6-smoke-test.ts --n 3                          # about $0.15, do this first
pnpm tsx scripts/extraction/simple_value_extractor.ts \
  --sample-from papers/staging/recent-bes-$(date +%F)-extraction-manifest-markdown.json \
  --input-format markdown --provider gateway
pnpm tsx scripts/extraction/sync-values-v2-to-db.ts --apply --only-missing
pnpm tsx scripts/extraction/audit-disk-vs-db.ts --fail-on-gap
# benchmark slice, 20 papers on CMA Opus v3
cd docs/corpus-screening-agent && ./launch.sh && ./poll.sh

pnpm tsx scripts/quality/backfill-condition-sets.ts --apply
papers/.venv/bin/python3 scripts/quality/backfill-canonical-slugs.py --apply --confident-only --target staging
papers/.venv/bin/python3 scripts/quality/backfill-canonical-slugs.py --apply --target staging
papers/.venv/bin/python3 scripts/quality/normalize-to-si.py            --apply --target staging
papers/.venv/bin/python3 scripts/quality/run-physics-checks.py         --apply --target staging
papers/.venv/bin/python3 scripts/quality/detect-contradictions.py      --apply --target staging
pnpm tsx scripts/db/backfill-verifier-passed.ts --apply
pnpm tsx scripts/derived/build-within-paper-input.ts
papers/.venv/bin/python3 services/ml-engine/training/fit_all_effects.py \
  --input services/ml-engine/data/within-paper-input.csv \
  --output services/ml-engine/training/artifacts/within-paper-effects.json
pnpm tsx scripts/derived/build-measure-priorities.ts
pnpm tsx scripts/acquisition/search-gaps-openalex.ts
pnpm dag:snapshot
pnpm verify:science

bash scripts/quality/refresh-all.sh --apply --target staging --skip-priors
pnpm tsx scripts/acquisition/search-gaps-openalex.ts
pnpm dag:snapshot && pnpm verify:science

Cost and time, per 100 papers

200 papers end to end: the cheap path is $10 to $20 and 4 to 6 hours mostly unattended. The high-fidelity path is about $188 and one overnight.

4a. Paper axes

Six TEXT or TEXT[] columns on ResearchPaper, none guarded by a Postgres enum. The taxonomy lives only in apps/web/src/lib/taxonomy/system-types.ts (TAXONOMY_VERSION = 2), so the writers are the only enforcement.

Three writer tiers, and the order matters. Run regex first, then the title and abstract classifier, then let full-text extraction fill the rest.

1. Regex, free. classifyByRegex() via scripts/classify-system-taxonomy.ts, also at OpenAlex ingest. Writes all 16 taxonomy columns. Skips taxonomyVersion = 2 unless --force. 7,822 papers carry taxonomySource = regex.
2. LLM on title and abstract, free on Cerebras. scripts/extraction/classify-title-abstract.ts. Only where primarySystemType IS NULL; Zod-validated, a parse failure never writes. 175 papers.
3. LLM on full text, paid. The v2 extractor's paper_header pass, landed by scripts/extraction/sync_taxonomy_to_db.ts, matched by DOI then pdfHash, COALESCE(new, existing) so nothing is wiped. 833 papers.

Two ordering traps. scripts/classify-paper-type.ts nulls primarySystemType when it is REVIEW or FUNDAMENTAL, treating them as leakage, and both other writers put them back, so the result depends on execution order. And three parallel system-type columns exist: primarySystemType (canonical), systemType (free text, 8 indexes, OpenAlex writes "BES"), and v1_1_primary_system_type (no writer, but read first by the benchmark export). They agree on 5,855 papers and differ on 1,572.

What you run per cohort: tier 1, then tier 2, then extraction. What you review: the 688 papers with needsReview = true, the 14,443 with a NULL confidence, and the 735 recent visible papers still untyped. Tier 3 human review has columns (taxonomyReviewedBy, taxonomyReviewedAt) and no writer, so nothing drains that queue. A minimal writer would be a script that takes a reviewed CSV of paper id, primarySystemType and reviewer, writes the two review columns plus taxonomySource = 'human', and refuses to run without a ref gate.

4b. Value ontology

Five stacked layers. A value must clear all of them to be modelable.

A raw name becomes a slug through four tiers: unit-aware rules first (bare "current" with /m² becomes currentDensity, "cod" with % becomes cod_removal, "cod" with mg/L becomes cod_concentration), then exact match on the alias index, then token-set ratio at or above 90 ("confident"), then token-sort ratio at or above 87 with a token-count ratio of 0.6 or more ("likely"). A single-word name with no exact hit is refused.

Your recurring jobs per cohort.

1. Run backfill-canonical-slugs.py --apply --confident-only --target staging, then the same without --confident-only, then normalize-to-si.py --apply --target staging.
2. Review the 79 pending_review entries in open-source/mess-parameters/data/parameter-aliases-extended.json. They include "th" → ph, "it" → ph and "which" → ph, the edit-distance false positives behind the pH incident that made 79.4% of ph rows implausible.
3. Add ParameterDefinition rows for the 29 slugs that appear in rows with no definition. membranematerial, cathodematerial, anodematerial, maxpowerdensity, mode, design and _provenance_metadata alone exceed 10,000 rows. A slug with no definition has no unit, range, category or foreign key, so it is invisible to the catalog and ungated by validation.
4. Keep open-source/mess-parameters/data/parameter-definitions-rich.json (pinned v0.2.0, 825 definitions) in step with staging (835), then regenerate the per-slug fixtures and pnpm dag:snapshot, which is currently 826 nodes.

4c. Acceptance criteria per cohort

4d. Experiment-coupling duties per cohort

The atomic unit for the platform's goal is the experiment record: a ConditionSet carrying a populated input vector AND at least one linked output, not the paper. scripts/quality/coupling-completeness.ts states this in its own header — the objective is conditional models P(outputs | inputs, system_type) per class. Papers are specialists, not generalists, so per-paper field fill-rate is the wrong metric, and scoring against a universal schema punishes exactly the diversity the corpus needs.

Per-cohort checklist.

5.1 What each extractor emits

5.2 Correction to scope this section against: three of the four assumed gaps already exist

The obvious hypothesis is that value_type, is_normalized_to, reference_electrode + voltage_reporting_convention, and per-observation condition binding are missing from v2 and need adding. Grepping the schema shows that is only true for one of them.

• value_type (peak vs steady-state) is already in v2 as three fields shipped 2026-05-08: phase (startup/steady_state/degradation/transient), value_kind (point/mean/peak/min/max/range_low/range_high/…), and derivation_method (polcurve_pmax, steady_state_at_rext, ocv_at_zero_current, tafel_backfit, …). The extractor's own prompt notes derivation_method coverage was under 7% before a 2026-community rule aggressively defaulted it — this is a fill-rate problem, not a schema gap.
• is_normalized_to (area basis) is already in v2 as normalization_basis (anode_projected_area / cathode_projected_area / membrane_area / reactor_volume), same rule family, same fill-rate caveat.
• reference_electrode is half-present: reference_electrode_type exists on the paper-level paper_header. voltage_reporting_convention (is a value vs Ag/AgCl, vs SHE, or a whole-cell voltage) is genuinely absent from v2 — this is the one real net-new Zod field.
• Condition-set binding on every observation is already in v2 as inline per-value fields (temperature_c, ph, substrate, hrt_hours, cod_mg_l, external_resistance_ohm) plus an explicit "Rule 2b COUPLING" prompt instruction shipped 2026-07-11 to fill them on every outcome row. The measured 27 full-tuple rows in the corpus (memory/project-extraction-coupling-gap-2026-07-11.md) is a fill-rate / extraction-reliability gap against a schema that already has the fields, not a missing field.

The one confirmed multiplier evidence in the repo: the methodology page's own "why" lines say conflating peak and steady-state values "produces 2-3× errors" and that area-basis mismatches run "1.5-3× to 10-1000×." The voltage-prior contamination incident (memory/project-include-v1-harmonization-2026-07-08.md) is a related but distinct failure — a non-MES cohort mis-canonicalized to voltage pushed the fitted mean to 53.9 V against a correct value near 0.5 V; that is a canonicalization defect, not a value_type / is_normalized_to schema gap. The 45% canonical-slug coverage figure is in the state strip in §1.

5.3 Tier B and Tier C

Tier B — next phase, high value.

Tier C — later.

5.4 The decision

5.5 What a new engineer must not assume

• The methodology page is not a contract with the active extractor — it describes the deprecated v1.2 orchestrator, not simple_value_extractor.ts.
• values_v2.json rows are not schema-blind on value type or normalization basis (phase/value_kind/normalization_basis exist), but fill rate on those fields is uneven — check the unit string and these fields by hand before comparing power densities across papers.
• The v1.2 prompt files under scripts/extraction/prompts/v1/ are live, working code, but the path is deprecated. Do not extend them.
• CMA output lands in a different shape (condition_sets + observations arrays keyed by condition_set_label, plus reactor_geometry, figures, unresolved) and its loader, docs/corpus-screening-agent/load-all.py, is local-only today.

Decisions that need an owner’s sign-off

Read next

• docs/onboarding/acquiring-recent-papers.md
• docs/onboarding/categorization-and-ontology.md
• docs/onboarding/paper-pipeline.md
• docs/onboarding/infra-access-r2-staging-prod.md
• .claude/skills/mes-paper-retrieval/SKILL.md
• .claude/skills/mes-parameter-extraction/SKILL.md
• .claude/skills/mes-data-harmonization/SKILL.md
• docs/corpus-refresh-architecture.md (design only)
• docs/corpus-screening-agent/CORPUS-DIAGNOSIS.md

Coupling is not wired into any gate today — coupling-completeness.ts is referenced only by a July 2026 handoff and a spec doc, and is run by hand. Nobody measures it during the corpus run. The two bugs below make every re-run worse.

Coupling is a shape before it is a number. One paper carries many ConditionSet rows — one per experimental condition it reports — and each set couples zero or more extracted values through conditionSetId:

Green boxes are linked outputs, the best-coupled rows in the corpus. The rose box is the real gap: an unlinked input row, not a missing output. Two systems share the word “experiment” in this schema — the corpus-derived ConditionSet + ExtractedParameterData pair measured below, and the user-authored Experiment / Run / Measurement notebook trio, which has no shared code path with extraction. Everything in this section is the first.

Measured against canonical staging (the canonical staging project; ref in docs/staging-access.md), 2026-09-08:

Two intuitions are wrong here, and both cost time if assumed. Outputs are NOT the unlinked side — they are the best-linked rows: powerDensity 91.8%, current_density_areal 86.0%, power_density_areal 83.3%, cod_removal 83.1%. The unlinked side is inputs: substrate 0.7%, ph 5.9%, temperature 8.5%. And this is NOT primarily a backfill problem — only 807 of 9,550 papers with extracted rows carry v2 rows (63,514 rows, 100% linked); the other 136,382 rows are legacy-extractor output carrying no inline conditions, 0% linked by construction. The free recovery pool caps at 3,678 rows (2,064 from v2-opus-max-2026-05-11, 1,127 from the llama v1.0 batch) — an estimated yield of low hundreds of complete records.

Two root causes.

1. scripts/quality/backfill-condition-sets.ts:210 calls createMany({ skipDuplicates: true }) against @@unique([paperId, label, runId]) at prisma/schema.prisma:3742, but never sets runId. Postgres treats NULLs as distinct, so the constraint never fires and every re-run mints a new generation.
2. scripts/extraction/sync-values-v2-to-db.ts:497 deletes a paper's v2 rows and re-inserts them (payload at :557) with conditionSetId unset, stranding the previous generation of sets.

Fix order.

Defects.

Fixes 1-3 remain prerequisites for any large v2 run, not optional cleanup (fix 4 landed in a8875ecd1). The 807-paper run produced 37,043 sets for 8,435 real tuples and orphaned 24,540 of them; running v2 over ten times the papers without these fixes reproduces that at ten times the scale.

Source: docs/onboarding/streamlined-corpus-run.md. Numbers measured on staging (canonical staging) 2026-09-07.

The user-facing surfaces: real, but a different feature and hard to find

apps/web/src/app/[lang]/experiments/[id]/page.tsx and apps/web/src/app/[lang]/runs/[id]/page.tsx are genuine server components — they call prisma.experiment.findUnique / prisma.run.findUnique directly, with force-dynamic, and render real rows, not mocked data. But they read the user-authored trio above, not ConditionSet. There is no listing page for either route, and the only inbound link anywhere in apps/web/src is one card on /projects/[id], which itself requires a signed-in session scoped to that user's own projects. There is no page anywhere in apps/web that lets a visitor browse the corpus's coupled experiment records — that story lives only in coupling-completeness.ts script output and the onboarding docs.

The corpus-wide coupling story on this page — 1,760 complete records, the two bugs above, the class-median result at 14 — has no dedicated UI at all today.

Measured 2026-09-07 on staging: papers with extracted rows already exceed papers with a PDF, and 55% of extracted rows have no canonical slug (45% do). The binding constraint is harmonization, not extraction. "Run more extraction" is usually the wrong lever.

The one command per stage

The five layers, and where each one stands (staging, 2026-09-08)

One home for this table. The five-layer state table — what exists at each layer, what it measured on staging, and the fix — lives in Part II · 00, section 0a, where it is actually used to plan a run and where each row links to the section that details it. It used to be restated here and in section 07 Platform map as well; three copies drift, and two of them did.

Order is not optional: coupling hygiene first (a large v2 run on today's backfill reproduces the 24,540 orphaned sets of the 807-paper run at ten times the scale), then the acquisition blockers, then extraction recency-first on the 1,405 papers from 2025–26, then vectorization, then gates and automation. Full sequence: docs/onboarding/streamlined-corpus-run.md §0b.

The same pipeline, as the public page describes it

messai.io/learn/science presents five stages — discover → resolve → extract → harmonise → sync — where the six-stage view above splits categorization out and carries promotion to the end. Same machine, different cut. Two properties it states that are worth holding on to: each stage is idempotent and resumable, so adding one PDF only triggers downstream work for that paper; and nothing is asserted that cannot be traced back to a sentence in a paper.

How a paper enters. Candidates come from CrossRef, PubMed, ArXiv, Unpaywall and OpenAlex, plus curated admin imports. Each PDF is fingerprinted by SHA-256, its DOI resolved, and it is hardlinked into a hash-keyed store. Deduplication runs at three layers — byte-identical SHA-256, DOI, and canonicalised title — so the same paper arriving from three sources becomes one record. The v2 extractor then makes its LLM call, Anthropic Haiku primary with Gemini or Groq fallback when the gateway is throttled — and the Gemini fallback is exactly the one that over-assigns OTHER at about 52% against about 14% on Haiku, so a throttled run silently degrades classification.

Trust is stratified by section: tables > methods > results > discussion, with a ±200-character window kept back to the source. A run is not “complete” until the disk→DB sync lands the rows with full provenance and the disk-vs-DB audit is clean — the same gate as audit-disk-vs-db.ts --fail-on-gap above.

The quality gate that decides what enters the training pool

Passing extraction is not the same as being trained on. Five conditions decide, and a paper failing any of them stays in the corpus with needs_review = true — visible, but out of the training set until cleared.

Public counts against measured counts

The public page carries dated snapshots; the numbers elsewhere in this Atlas are re-measured on staging. They are close, and the gaps are all explainable — but quote the measured column, with its date.

Two different things hide under "categorization". A paper is classified on six axes (which reactor, which subtype, which coupling, what kind of study, which application, what document). A value extracted from that paper is classified through five stacked ontology layers before it can be modeled. All counts below are staging, ref , measured 2026-09-07.

The corpus funnel

Six axes on a paper

All six are plain TEXT or TEXT[] columns on ResearchPaper. No Postgres enum guards any of them; the 17-type taxonomy lives only in apps/web/src/lib/taxonomy/system-types.ts (TAXONOMY_VERSION 2), so the writers are the only enforcement.

Who writes the class, in what order

The parameter ontology: five stacked layers

A raw string like "Power Density" with unit "mW/m2" passes through five independent layers. They are not one taxonomy and they do not nest. Layer 1 is for browsing; layer 3 is the physics; the modelable gate lives at layer 3, not layer 1.

How a raw name becomes a slug

The LLM alias classifier (classify-raw-names-with-catalog.ts, Haiku via the Gateway) only edits the alias data file; the DB changes solely through the deterministic backfill. The extended file's 79 pending_review entries include "th" → ph, "it" → ph, "which" → ph: exactly the edit-distance false positives behind the pH incident (79.4% implausible, ISBNs scraped as pH, fixed on LOCAL only in PR #750). ph is the largest slug in the corpus at 12,280 rows.

The catalog file, and its sync pipeline

open-source/mess-parameters/data/parameter-definitions-rich.json is a flat array of 825 entries (measured 2026-09-08; package.json's own description still says “704 parameters”, stale, ignore it). Each entry carries 23 fields: identity (id, slug, name, category, subcategory), typing (unit, data_type, min_value, max_value, allowed_values, is_required), and prose (definition, typical_values, measurement_methods, affecting_factors, performance_impact, limitations, cost_analysis, related_parameters, references, compatible_systems, priority, usage_count). It is a generated artifact, not a hand-edit target — the database has been the source of truth since e0f66f500 (07), which is what the 825-vs-835 gap two tables up (09) actually is: rich.json waiting on its next regeneration.

Step 3 is wired into apps/web's prebuild, so every local or Vercel build regenerates the catalog from whatever rich.json happens to be on disk at build time. Step 2's 10% ceiling is a safety refusal, not a cleanup convenience: a truncated rich.json fails loudly instead of silently archiving hundreds of fixtures.

The real /parameters/* route map

/parameters/dag, /parameters/correlations, /parameters/global, /parameters/methodology, and apps/web's own copy of /parameters/sweep are not standalone pages — all five redirect into /parameters?tab=…. apps/web's /parameters/sweep stub is additionally dead in any zoned environment: the multi-zone rewrite sends that exact path to apps/lab instead. Run pnpm dev alone, with no LAB_ZONE_URL set, and the dead apps/web stub is what actually serves — use pnpm dev:zones to see the real sweep UI locally.

Protocols — a separate, much smaller ontology

/protocols, shipped July 2026, is a second knowledge graph that is easy to mistake for a corpus-mined companion to the parameter DAG above. It is not: it is a hand-authored reference ontology of experimental procedure steps (prepare growth medium, heat-treat the anode, set electrode spacing, …), with edges of type precedes / requires / alternative_to / produces between them. Four lenses share one data substrate behind a single shell — method graph, an ordered protocol DAG, a drag-and-build protocol builder, and a method→outcome overlay — switched via ?view= with a shared ?step= selection.

Every one of the 68 edges carries learnedFromData: false, paperSupportCount: 0, and coOccurrence: 0; all 53 nodes carry provenance.basis: "curated", though the type system allows corpus and hybrid nodes that don't exist yet. No Prisma model backs any protocol node, edge, or step, and there is no /api/protocols* route — the client fetches a static protocol-snapshot.json directly, regenerated by hand via pnpm protocols:snapshot, not by the web prebuild. Vocabulary (10 process stages, 6 categories, 4 edge types) is defined once locally and never imported from the canonical system-types.ts taxonomy — the cost shows up in the corpus-evidence file's system histogram, which contains an unvalidated code, “MESNORK”, leaking straight through from raw corpus data.

Acquisition has been stalled since May. The last OpenAlex discovery cursor is 2026-05-09, the last PDF landed 2026-08-06, and no paper row has been created since July. The 2025–2026 literature in staging is mostly metadata: 1,405 visible papers, 322 with a PDF. Twelve steps get new papers all the way to analysis today; four of them need a workaround and one is broken.

The twelve steps, and which ones work as written

Scripts that silently target whatever DATABASE_URL is loaded

Full runbook with every command, the env block that points a shell at staging safely, and the per-step DB target: docs/onboarding/acquiring-recent-papers.md.