formlab-mcp 0.6.24 → 0.6.26

package/README.md

@@ -34,19 +34,20 @@ Ask Claude (or another MCP client) things like:
 | `compare_formulations` | Pairwise side-by-side composition diff |
 | `list_ingredients` | Filtered list of raw materials. Filters: `family`, `supplier`, `name_contains`, `in_stock_only`, `ingredient_class` (small-molecule / surfactant / polymer / extract / fragrance / pigment / sequence / mixture), `sequence_contains` (e.g. `KTTKS` → Matrixyl), `taxon_contains` (e.g. `Centella`) |
 | `get_ingredient` | Full record + supplier / **cost ($/kg)** / stock / chemical name / molecular weight / storage / formulations using it, plus **GHS safety** (pictograms, H/P codes, signal word), **per-jurisdiction regulatory status**, **approved sources** (the suppliers / manufacturers qualified to supply this material — ASL/AML), and **inventory lots** (balances + expiry + the source each was received from). Returns every class-specific sub-object when present: `sequence` (peptide / oligo), `taxon` (NCBI ID + scientific name), `ingredientClass`, `extractDetails`, `sequenceDetails`, `polymerDetails`, `surfactantDetails`, `pigmentDetails`, `fragranceDetails` |
-| `list_lots` | Inventory lots across ingredients (each a received batch with its own remaining balance, supplier, expiry, **unit cost**, **status** — `active` / `hold` / `quarantine` / `rejected`; held lots are blocked from consumption, with a `holdReason` — and the **approved source** it was received from: `source.supplier` + `source.manufacturer`, where recalls hinge on the manufacturer). Filters: `ingredient_id`, `expiring_within_days`, `status` (e.g. `hold` to find lots held for a recall) |
+| `list_lots` | Inventory lots across ingredients (each a received batch with its own remaining balance, supplier, expiry, **unit cost**, **status** — `active` / `hold` / `quarantine` / `rejected`; held lots are blocked from consumption, with a `holdReason` — and the **approved source** it was received from: `source.supplier` + `source.manufacturer`, where recalls hinge on the manufacturer). Each lot also reports its **Certificate of Analysis** (`coa`: linked, or matched by lot number) and `coaMissing` for an in-stock lot without one. Filters: `ingredient_id`, `expiring_within_days`, `status` (e.g. `hold` to find lots held for a recall), `missing_coa` |
 | `list_suppliers` | Supplier / manufacturer records with roll-ups — ingredients approved, lots received / on hand (+ value at paid cost), qualified / trial / disqualified source counts, last receipt; lots count by supplier **and** by manufacturer |
 | `get_supplier` | One supplier in full: record, every ingredient it's an approved source for, every lot from it, and the **recall trace** (batches that consumed those lots → products, shipments, samples, sub-batches; lots on hold flagged) |
+| `list_documents` | The document register (same as the app's Documents page): ingredient SDS / PDS / CoA / other with lot, version, source and expiry; test and notebook attachments; per-record uploads and links (formulas, batches, samples, suppliers, equipment…). File **metadata** only, never the text inside a file. Filters: `type`, `record`, `linked`, `query`, `lot`, `format`, `expiry`, `expiring_within_days`, `without_expiry`, `uploaded_within_days`. A `summary` block carries the page's tile counts: expired, expiring in 30 days, SDS/CoA without expiry, ingredients missing an SDS (+ coverage %), lots in stock without a CoA, added last 7 days |
 | `list_inventory` | Portfolio stock rollup — one row per ingredient with on-hand qty, summed lot balance, nearest expiry, and a low-stock flag (on-hand ≤ `reorderThreshold`, or zero). Filters: `low_stock_only`, `expiring_within_days`, `family` |
 | `list_batches` | Filtered list of production / lab-prep events |
 | `get_batch` | Full record + actual composition, measured/derived **actual volume** (mass ÷ density, never a sum of per-ingredient volumes) and **actual mass** (yield, else summed as-prepared inputs — mL rows through that ingredient's density — else measured volume × density), **estimatedVolume** (mass ÷ the formula's finished density when no actual exists, flagged `estimate: true`), **plannedMass** for volume-target batches (target × finished density) and **formulaFinishedDensity**, the **process** method + any **process-factor values** (DOE inputs), samples + blend lineage, and — as a finished-goods lot — its storage **`location`** + finished-goods **`stockLedger`** (shipments out + adjustments; `shippedQty` total) |
 | `list_samples` | Filtered list of physical specimens |
 | `get_sample` | Full record + canonical variant + test reports + blend lineage |
 | `list_test_results` | Filtered list of test reports (by sample, parameter, **measured-value range** (`value_min`/`value_max`), date, or lab) |
-| `get_test_result` | Full report: every measurement's value, spec, any per-measurement run **conditions**, and the **resolved instrument** (`instrumentSource`: row / method / run). Complex types carry a `representative` (time-series → final, distribution → D50); a time series adds `aggregated` (per-timestamp mean ± sd) and `pointReplicates` (repeat readings at one `t`). Report-level `seriesReplicates` lists parameters measured 2+ times as separate rows — point vs series replicates are distinct |
+| `get_test_result` | Full report: every measurement's value, spec, any per-measurement run **conditions**, and the **resolved instrument** (`instrumentSource`: row / method / run). Complex types carry a `representative` (time-series → final, distribution → D50); a time series adds `aggregated` (per-timestamp mean ± sd) and `pointReplicates` (repeat readings at one `t`). Report-level `seriesReplicates` lists parameters measured 2+ times as separate rows — point vs series replicates are distinct. Each measurement also gives its **effective spec** (`effectiveSpec`, `specSource`: override / template / parameter / none) and `passFail` — panel and Test Method specs apply exactly as in the app, and every pass/fail count across the tools uses the same rule |
 | `get_doe_matrix` | Pivot matrix (CSV by default) — rows × ingredients × parameters |
-| `find_failures` | Pareto-style: parameters that fail acceptance most often |
-| `get_coverage_matrix` | Which formulations × parameters have been measured (TEST coverage) |
+| `find_failures` | Parameters ranked by failure **rate** (failing ÷ all readings; replicates in one report count once), `lowN` flag under 5 readings, plus formulations ranked by share of failing reports — same numbers as the app's Test Analytics → Failures |
+| `get_coverage_matrix` | TEST coverage by formulation, batch or sample (`grain`) × parameter. Each cell is the **latest** reading by test date (same-day reports averaged, any fail → fail) with its date and how many reports measured it — same rollup as the app's Test Analytics → Coverage |
 | `compare_batches` | Reproducibility of 2+ runs (ideally of one formula): each run's **yield %**, actual produced mass, cost/kg; per-ingredient **drift** across the runs vs the formula's proposed wt-%; and the biggest **outlier** run. `basis`: `wt_percent` (default) or `amount` |
 | `get_batch_pivot` | Production analytics — aggregate batches by `group_by` (formula / status / month / prepared_by / project) × `metric` (count, avg_yield_pct, total_produced_kg, avg_cost_per_batch, total_samples, total_tests), with share + total for additive metrics. Optional `batch_uids` scope + `status` filter |
 | `get_project_pivot` | Portfolio analytics — aggregate projects by `group_by` (status / phase / priority / business_unit / site / customer / lead, or `cf:<custom field>`) × `metric` (count, total_formulas / batches / samples, total_cost, avg_formulas / batches / cost_per_batch), rolling child activity + cost up by any project attribute. Optional `project_uids` scope |
@@ -54,7 +55,7 @@ Ask Claude (or another MCP client) things like:
 | `get_design_space` | COMPOSITION design space for one project: which ingredients vary and over what observed wt-% ranges (ranked), an occupied-region summary ("where you've been"), the biggest untested **interior gap** as ready-to-seed DOE ranges (a combination you could have made but skipped), and an optional standardised **2-component PCA** of all varying ingredients — loadings, variance-explained, scree, and a full-dimensional gap. Matches the in-app Design Space Viewer exactly. Answers *"where haven't I explored?"* / *"what should I formulate next?"* |
 | `list_doe_designs` | Saved DOE designs — the *recipe* behind each batch of runs: design type, factors + ranges, constraints, run count, D-efficiency. Filters: `project`, `design_type`, `constrained_only`, `name_contains` |
 | `get_doe_design` | One design in full: constraints in plain language, the model it was optimised for, generation settings (run budget, replicates, centre points, seed) and the complete run matrix with the formulation each run became |
-| `find_by_smarts` | SMARTS-pattern substructure search across every ingredient with a SMILES. Requires `@rdkit/rdkit` (optional dependency — install with `npm install @rdkit/rdkit` in `mcp/` if you get a "not installed" error). Examples: `c1ccccc1` (any aromatic 6-ring), `[OX2H1]` (any hydroxyl), `C(=O)O` (carboxylic acid), `[F,Cl,Br,I]` (any halogen). |
+| `find_by_smarts` | SMARTS-pattern substructure search across every ingredient with a SMILES; peptides that only store a sequence are searched with the structure derived from it, as the app draws them (`smilesDerived: true`). Requires `@rdkit/rdkit` (optional dependency — install with `npm install @rdkit/rdkit` in `mcp/` if you get a "not installed" error). Examples: `c1ccccc1` (any aromatic 6-ring), `[OX2H1]` (any hydroxyl), `C(=O)O` (carboxylic acid), `[F,Cl,Br,I]` (any halogen). |
 | `list_equipment` | Filtered list of the Equipment registry (mixers, ovens, viscometers, balances…). Filters: `category`, `status`, `manufacturer`, `name_contains` |
 | `get_equipment` | Full equipment record + `usedIn` (panels, step presets, test methods, formula steps, batches, testReports resolved to it), `usage` (reports / formulas / batches / samples / pass rate / top formulas) and `measured` (per parameter: mean here vs mean on other instruments, biasPct) |
 | `list_test_methods` | Filtered list of Test Methods (the parameter library). Filter by `analyte` (the property measured, e.g. `Viscosity` — finds every method for it), `category`, `name_contains`, `include_retired` |
@@ -151,7 +152,7 @@ Or for local-dev (from the repo):
 }
 ```
 
-Restart Claude Desktop. You should see a hammer icon indicating tools are available, and FormLab's 39 tools become callable in any conversation.
+Restart Claude Desktop. You should see a hammer icon indicating tools are available, and FormLab's 40 tools become callable in any conversation.
 
 ## Wire it up to Claude Code
 

package/index.js

@@ -7,7 +7,7 @@
 //   FORMLAB_EXPORT=/path/to/export.json node index.js
 //   formlab-mcp /path/to/export.json   (when installed via npm)
 //
-// Exposes 37 tools (see ./tools/) over stdio. The MCP host (Claude
+// Exposes 40 tools (see ./tools/) over stdio. The MCP host (Claude
 // Desktop, Claude Code, etc.) handles tool discovery, invocation
 // and response formatting. We just register handlers and stay out
 // of the way.
@@ -39,6 +39,7 @@ import * as projects     from './tools/projects.js';
 import * as notebook     from './tools/notebook.js';
 import * as batchAnalyze from './tools/batch-analyze.js';
 import * as suppliers    from './tools/suppliers.js';
+import * as documents    from './tools/documents.js';
 
 // ----- Data source: LIVE cloud workspace OR a static export file -----
 // Cloud mode kicks in when a dedicated read-only MCP token is present (mint it
@@ -119,6 +120,7 @@ const TOOLS = [
   ...Object.values(projects.tools),
   ...Object.values(notebook.tools),
   ...Object.values(suppliers.tools),
+  ...Object.values(documents.tools),
   ...Object.values(batchAnalyze.tools),
 ];
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "formlab-mcp",
-  "version": "0.6.24",
+  "version": "0.6.26",
   "mcpName": "io.github.juliu1980/formlab-mcp",
   "description": "Read-only Model Context Protocol server for FormLab \u2014 lets Claude (and other MCP clients) read and analyze your FormLab data, from a local export file OR your live cloud workspace.",
   "type": "module",

package/peptide.js

@@ -0,0 +1,65 @@
+// Peptide sequence → SMILES, ported from the app's js/peptide-compute.js
+// (peptideToSmiles, 2026-09-14) so find_by_smarts sees peptides that only
+// store a sequence, exactly as the app draws them. Keep the two in step:
+// H-[NH-CHR-CO]n-OH, L-amino acids, Pro / 4-Hyp as ring residues, known
+// terminal modifications; unknown tokens are skipped, never invented.
+
+const RESIDUES = new Set('ARNDCEQGHILKMFPSTWYVO'.split(''));   // O = 4-hydroxyproline (collagen)
+const TOKEN_ALIASES = { hyp: 'O' };
+const NTERM_MODS = ['Pal', 'Ac', 'Boc', 'Fmoc', 'Myr', 'Bz'];
+const CTERM_MODS = ['NH2', 'OMe'];
+
+const SIDECHAIN = {
+  A: 'C', R: 'CCCNC(=N)N', N: 'CC(N)=O', D: 'CC(=O)O', C: 'CS', E: 'CCC(=O)O', Q: 'CCC(N)=O',
+  H: 'Cc1c[nH]cn1', I: '[C@@H](C)CC', L: 'CC(C)C', K: 'CCCCN', M: 'CCSC', F: 'Cc1ccccc1',
+  S: 'CO', T: '[C@H](O)C', W: 'Cc1c[nH]c2ccccc12', Y: 'Cc1ccc(O)cc1', V: 'C(C)C',
+};
+const FRAGMENT = {
+  G: 'NCC(=O)',
+  P: 'N1CCC[C@H]1C(=O)',
+  O: 'N1C[C@H](O)C[C@H]1C(=O)',
+};
+const NTERM_SMILES = {
+  Ac: 'CC(=O)', Pal: 'CCCCCCCCCCCCCCCC(=O)', Myr: 'CCCCCCCCCCCCCC(=O)', Bz: 'c1ccccc1C(=O)',
+  Boc: 'CC(C)(C)OC(=O)', Fmoc: 'O=C(OCC1c2ccccc2-c2ccccc12)',
+};
+const CTERM_SMILES = { NH2: 'N', OMe: 'OC' };
+
+const tokenize = (raw) => (typeof raw === 'string' && raw) ? raw.split('-').map(s => s.trim()).filter(Boolean) : [];
+function residues(tokens) {
+  const out = [];
+  for (const tok of tokens) {
+    const alias = TOKEN_ALIASES[tok.toLowerCase()];
+    if (alias) { out.push(alias); continue; }
+    if (/^[A-Z]+$/.test(tok)) for (const ch of tok) if (RESIDUES.has(ch)) out.push(ch);
+  }
+  return out;
+}
+function modAt(tokens, idx, list, minLen) {
+  if (tokens.length < minLen) return null;
+  const tok = tokens[idx];
+  if (/^[A-Z]+$/.test(tok)) return null;
+  return list.find(k => k.toLowerCase() === tok.toLowerCase()) || null;
+}
+
+export function peptideToSmiles(rawSequence) {
+  const tokens = tokenize(rawSequence);
+  const aas = residues(tokens);
+  if (!aas.length) return null;
+  const body = aas.map(aa => FRAGMENT[aa] || `N[C@@H](${SIDECHAIN[aa]})C(=O)`).join('');
+  const n = modAt(tokens, 0, NTERM_MODS, 1);
+  const c = modAt(tokens, tokens.length - 1, CTERM_MODS, 2);
+  return (n ? NTERM_SMILES[n] : '') + body + (c ? CTERM_SMILES[c] : 'O');
+}
+
+// The SMILES an ingredient is searched with: stored SMILES, else (non-oligo
+// sequence) the derived peptide SMILES. Returns { smiles, derived }.
+export function ingredientSmiles(ing) {
+  if (ing && ing.smiles) return { smiles: ing.smiles, derived: false };
+  const seq = ing && ing.sequence;
+  if (seq && seq.raw && seq.type !== 'oligo') {
+    const s = peptideToSmiles(seq.raw);
+    if (s) return { smiles: s, derived: true };
+  }
+  return { smiles: '', derived: false };
+}

package/server.json

@@ -2,7 +2,7 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.juliu1980/formlab-mcp",
   "description": "Read-only MCP for FormLab — let Claude query your formulation lab. Free reads a local export; Pro connects to your live cloud workspace with a dedicated read-only token.",
-  "version": "0.6.22",
+  "version": "0.6.26",
   "websiteUrl": "https://formvix.com/mcp",
   "repository": {
     "url": "https://github.com/juliu1980/FormLab",
@@ -13,7 +13,7 @@
     {
       "registryType": "npm",
       "identifier": "formlab-mcp",
-      "version": "0.6.22",
+      "version": "0.6.26",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

package/tools/analytics.js

@@ -111,6 +111,9 @@ function _trimMeasurement(m, t, db) {
     binCount: Array.isArray(m.bins) ? m.bins.length : 0,
     ...complex,
     acceptanceCriteria: m.acceptanceCriteria || null,
+    // Effective spec + where it came from (override | template | parameter | none)
+    // and the app's pass/fail verdict under it.
+    ...(() => { const r = _resolveSpec(m, t && t.templateId, db); return { effectiveSpec: r.spec || null, specSource: r.source, passFail: _evalPassFail(m, t && t.templateId, db) }; })(),
     // Captured run conditions this reading was measured under (e.g.
     // {Storage: "40 °C / 75% RH"}, {RPM: "50"}) — the condition travels with the
     // value, so a reading is self-describing and comparable across runs. Present
@@ -383,10 +386,65 @@ const get_doe_matrix = {
   },
 };
 
+// ---- Shared reading flattener (mirrors the app's _taFlattenMeasurements) ----
+// One row per reading with a representative number (scalar → value,
+// time_series → final point mean, distribution → D50) and pass/fail. Replicates
+// — the same parameter measured more than once in ONE report under the SAME run
+// conditions — collapse into a single timepoint (numeric mean, any fail → fail),
+// so a parameter measured 3× on one occasion counts once in failure rates and
+// coverage, exactly as Test Analytics does.
+const FAIL_MIN_N = 5;   // app: _TA_FAIL_MIN_N — rates on fewer readings are "low n"
+function _mcpRepNumber(m) {
+  const type = m.type || 'scalar';
+  if (type === 'time_series' && Array.isArray(m.points) && m.points.length) {
+    const agg = _mcpTsAggregate(m.points);
+    const last = agg[agg.length - 1];
+    return last ? last.mean : null;
+  }
+  if (type === 'distribution' && Array.isArray(m.bins) && m.bins.length) {
+    const d50 = m.bins.find(b => String(b.label || '').toUpperCase().replace(/\s/g, '') === 'D50');
+    const v = d50 ? parseFloat(d50.value) : NaN;
+    return isFinite(v) ? v : null;
+  }
+  const v = parseFloat(m.value);
+  return isFinite(v) ? v : null;
+}
+function _mcpCondSig(m) {
+  const c = m && m.conditions;
+  if (!c || typeof c !== 'object') return '';
+  return Object.keys(c).filter(k => c[k] != null && c[k] !== '').sort().map(k => `${k}=${c[k]}`).join('|');
+}
+function _mcpFlattenReadings(tests, indexes, paramFilter) {
+  const norm = (s) => String(s || '').toLowerCase();
+  const groups = new Map(); const order = [];
+  for (const t of tests) {
+    const samp = indexes.samplesById.get(t.sampleId) || null;
+    const formulation = samp && samp.formulationId ? indexes.formulationsById.get(samp.formulationId) || null : null;
+    for (const m of (t.measurements || [])) {
+      if (!m) continue;
+      const parameter = String(m.parameter || '').trim();
+      if (!parameter) continue;
+      if (paramFilter && !norm(parameter).includes(norm(paramFilter))) continue;
+      const row = { test: t, sample: samp, formulation, parameter, numeric: _mcpRepNumber(m), value: m.value, unit: m.unit || '', pf: _evalPassFail(m, t.templateId), m };
+      const key = (t.id || t.uid) + '|' + parameter + '|' + _mcpCondSig(m);
+      if (!groups.has(key)) { groups.set(key, []); order.push(key); }
+      groups.get(key).push(row);
+    }
+  }
+  return order.map(k => {
+    const g = groups.get(k);
+    if (g.length === 1) return g[0];
+    const nums = g.map(r => r.numeric).filter(v => v != null && isFinite(v));
+    const mean = nums.length ? nums.reduce((a, b) => a + b, 0) / nums.length : null;
+    const pf = g.some(r => r.pf === 'fail') ? 'fail' : g.some(r => r.pf === 'pass') ? 'pass' : g[0].pf;
+    return { ...g[0], numeric: mean, value: mean != null ? mean : g[0].value, pf, replicates: g.length };
+  });
+}
+
 const find_failures = {
   definition: {
     name: 'find_failures',
-    description: 'Pareto-style failure analysis: which test parameters fail their acceptance criteria most often, and on which samples / formulations. Returns ranked list of (parameter, failureCount, failureRate, exampleFailures).',
+    description: 'Failure analysis matching the app\'s Test Analytics → Failures tab: test parameters ranked by failure RATE (failing ÷ all readings, replicates in one report under the same run conditions counted once), worst rate first, count breaking ties. Rates on fewer than 5 readings carry lowN: true and are tentative. Also ranks formulations by the share of their test reports that fail. Returns ranked (parameter, totalMeasured, failureCount, failureRate %, lowN, exampleFailures) plus formulations.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -403,38 +461,30 @@ const find_failures = {
     const limitExamples = Math.min(20, Math.max(1, args.limit_examples_per_param || 5));
     const norm = (s) => String(s || '').toLowerCase();
 
-    // Per-parameter aggregator
+    const tests = (db.testResults || []).filter(t => t && !t._trashed && !(args.since_date && (t.testDate || '') < args.since_date));
+    const flat = _mcpFlattenReadings(tests, indexes, args.parameter);
+
+    // Per-parameter aggregator (over timepoints, like the app)
     const byParam = new Map();
-    (db.testResults || []).forEach(t => {
-      if (!t || t._trashed) return;
-      if (args.since_date && (t.testDate || '') < args.since_date) return;
-      (t.measurements || []).forEach(m => {
-        if (!m || !m.parameter) return;
-        if (args.parameter && !norm(m.parameter).includes(norm(args.parameter))) return;
-        if (!byParam.has(m.parameter)) {
-          byParam.set(m.parameter, { total: 0, failures: 0, examples: [] });
-        }
-        const agg = byParam.get(m.parameter);
-        agg.total += 1;
-        const pf = _evalPassFail(m);
-        if (pf === 'fail') {
-          agg.failures += 1;
-          if (agg.examples.length < limitExamples) {
-            const samp = indexes.samplesById.get(t.sampleId);
-            const f = samp?.formulationId ? indexes.formulationsById.get(samp.formulationId) : null;
-            agg.examples.push({
-              testId: t.uid || t.id,
-              testDate: t.testDate || '',
-              sample: samp ? (samp.uid || samp.id) : '',
-              formulation: f ? (f.name || f.uid) : '',
-              value: m.value,
-              unit: m.unit,
-              spec: m.acceptanceCriteria || null,
-            });
-          }
-        }
-      });
-    });
+    for (const r of flat) {
+      if (!byParam.has(r.parameter)) byParam.set(r.parameter, { total: 0, failures: 0, examples: [] });
+      const agg = byParam.get(r.parameter);
+      agg.total += 1;
+      if (r.pf !== 'fail') continue;
+      agg.failures += 1;
+      if (agg.examples.length < limitExamples) {
+        agg.examples.push({
+          testId: r.test.uid || r.test.id,
+          testDate: r.test.testDate || '',
+          sample: r.sample ? (r.sample.uid || r.sample.id) : '',
+          formulation: r.formulation ? (r.formulation.name || r.formulation.uid) : '',
+          value: r.value,
+          unit: r.unit,
+          spec: _resolveSpec(r.m, r.test.templateId).spec || null,
+          ...(r.replicates ? { replicatesAveraged: r.replicates } : {}),
+        });
+      }
+    }
 
     const ranked = [...byParam.entries()]
       .map(([param, agg]) => ({
@@ -442,49 +492,134 @@ const find_failures = {
         totalMeasured: agg.total,
         failureCount: agg.failures,
         failureRate: agg.total ? +(agg.failures / agg.total * 100).toFixed(2) : 0,
+        lowN: agg.total < FAIL_MIN_N,
         examples: agg.examples,
       }))
       .filter(r => r.failureCount > 0)
-      .sort((a, b) => b.failureCount - a.failureCount)
+      .sort((a, b) => b.failureRate - a.failureRate || b.failureCount - a.failureCount)
       .slice(0, limitParams);
 
+    // Formulations by share of failing test reports (a report fails when any
+    // of its readings fails).
+    const byForm = new Map();
+    const failingTests = new Set(flat.filter(r => r.pf === 'fail').map(r => r.test));
+    for (const t of tests) {
+      const samp = indexes.samplesById.get(t.sampleId);
+      const f = samp && samp.formulationId ? indexes.formulationsById.get(samp.formulationId) : null;
+      if (!f) continue;
+      const cur = byForm.get(f.id) || { formulation: f.name || f.uid, formulationId: f.uid || f.id, reports: 0, failingReports: 0 };
+      cur.reports += 1;
+      if (failingTests.has(t)) cur.failingReports += 1;
+      byForm.set(f.id, cur);
+    }
+    const formulations = [...byForm.values()]
+      .filter(r => r.failingReports > 0)
+      .map(r => ({ ...r, failureRate: +(r.failingReports / r.reports * 100).toFixed(2), lowN: r.reports < FAIL_MIN_N }))
+      .sort((a, b) => b.failureRate - a.failureRate || b.failingReports - a.failingReports)
+      .slice(0, 8);
+
     return {
       totalParamsConsidered: byParam.size,
       paramsWithFailures: ranked.length,
+      rateBasis: 'failing readings ÷ all readings of the parameter; replicates in one report under the same run conditions count once; lowN = fewer than 5 readings',
       ranked,
+      formulations,
     };
   },
 };
 
-// Minimal pass/fail evaluator — mirrors FormLab's _evalPassFail logic
-// for scalar numeric measurements with min/max/target acceptance.
-function _evalPassFail(m) {
-  if (!m || m.value == null || m.value === '') return 'untested';
-  const spec = m.acceptanceCriteria;
-  if (!spec) return 'no-criteria';
-  const v = parseFloat(m.value);
-  if (!isFinite(v)) {
-    // Non-numeric required value
-    if (spec.requiredValue != null) {
-      return String(m.value).trim() === String(spec.requiredValue).trim() ? 'pass' : 'fail';
+// Effective acceptance spec for a reading — mirrors the app's _resolveSpec
+// (js/views/testing.js): the reading's own spec ('override'), else the test
+// panel's row for that parameter ('template'; matched by a LIVE parameterId,
+// else by trimmed name), else the Test Method library default ('parameter').
+function _resolveSpec(m, templateId, db) {
+  if (!m) return { spec: null, source: 'none' };
+  if (m.acceptanceCriteria) return { spec: m.acceptanceCriteria, source: 'override' };
+  const store = db || getStore().db;
+  if (templateId) {
+    const tmpl = (store.templates || []).find(t => t && t.id === templateId);
+    const pid = m.parameterId || '';
+    const name = String(m.parameter || '').trim();
+    const pidLive = !!(pid && (store.parameters || []).some(p => p && p.id === pid));
+    const row = ((tmpl && tmpl.parameters) || []).find(p =>
+      (pidLive && p.parameterId === pid) ||
+      (!pidLive && String((p.parameter || p.name) || '').trim() === name));
+    if (row && row.acceptanceCriteria) return { spec: row.acceptanceCriteria, source: 'template' };
+  }
+  if (m.parameterId) {
+    const lib = (store.parameters || []).find(p => p && p.id === m.parameterId);
+    if (lib && lib.acceptanceCriteria) return { spec: lib.acceptanceCriteria, source: 'parameter' };
+  }
+  return { spec: null, source: 'none' };
+}
+
+const _MEAS_TYPES = ['scalar', 'ordinal', 'categorical', 'time_series', 'distribution'];
+function _measType(m) {
+  if (!m) return 'scalar';
+  if (m.type && _MEAS_TYPES.includes(m.type)) return m.type;
+  return m.valueType === 'Categorical' ? 'categorical' : 'scalar';
+}
+function _ordinalMinRank(crit, scale) {
+  if (!crit) return null;
+  if (crit.minValue != null) { const i = (Array.isArray(scale) ? scale : []).indexOf(crit.minValue); return i >= 0 ? i : null; }
+  return crit.minRank != null ? crit.minRank : null;
+}
+
+// Pass / fail for one reading — mirrors the app's _evalPassFail per type.
+// Pass the parent test's templateId so panel specs apply (as the app does).
+// Returns 'pass' | 'fail' | 'no-criteria' | 'untested'.
+function _evalPassFail(m, templateId, db) {
+  const crit = _resolveSpec(m, templateId, db).spec;
+  if (!crit) return 'no-criteria';
+  const type = _measType(m);
+  const raw = String(m?.value ?? '').trim();
+  if (type === 'scalar') {
+    if (!raw) return 'untested';
+    const v = parseFloat(raw);
+    if (!isFinite(v)) return 'untested';
+    if (crit.target != null && v !== crit.target) return 'fail';
+    if (crit.min != null && v < crit.min) return 'fail';
+    if (crit.max != null && v > crit.max) return 'fail';
+    return 'pass';
+  }
+  if (type === 'ordinal') {
+    if (!raw) return 'untested';
+    const scale = Array.isArray(m.scale) ? m.scale : [];
+    const idx = scale.indexOf(raw);
+    if (idx < 0) return 'untested';
+    const minRank = _ordinalMinRank(crit, scale);
+    if (minRank == null) return 'no-criteria';
+    return idx >= minRank ? 'pass' : 'fail';
+  }
+  if (type === 'categorical') {
+    if (!raw) return 'untested';
+    if (!crit.requiredValue) return 'no-criteria';
+    return raw.toLowerCase() === String(crit.requiredValue).toLowerCase() ? 'pass' : 'fail';
+  }
+  if (type === 'time_series' || type === 'distribution') {
+    const list = type === 'time_series' ? (Array.isArray(m.points) ? m.points : []) : (Array.isArray(m.bins) ? m.bins : []);
+    if (!list.length) return 'untested';
+    for (const p of list) {
+      const v = parseFloat(p.value);
+      if (!isFinite(v)) return 'untested';
+      if (crit.min != null && v < crit.min) return 'fail';
+      if (crit.max != null && v > crit.max) return 'fail';
     }
-    return 'no-criteria';
+    return 'pass';
   }
-  if (spec.target != null) return Math.abs(v - parseFloat(spec.target)) <= (spec.tolerance ?? 0) ? 'pass' : 'fail';
-  if (spec.min != null && v < parseFloat(spec.min)) return 'fail';
-  if (spec.max != null && v > parseFloat(spec.max)) return 'fail';
-  return 'pass';
+  return 'no-criteria';
 }
 
 const get_coverage_matrix = {
   definition: {
     name: 'get_coverage_matrix',
-    description: 'Coverage map: which formulations have been tested on which parameters. Returns counts per (formulation × parameter) cell so the LLM can answer "what\'s untested" or "what\'s been measured many times" questions.',
+    description: 'Coverage matrix matching the app\'s Test Analytics → Coverage: rows = sample, batch or formulation (grain), columns = parameters. Each cell is the LATEST reading by test date; readings from several reports on that same date are averaged and fail if any of them fails. Each cell also gives latestDate, reportsAveraged and nReports (how many reports measured it). Empty = never tested. Use for "what\'s untested", "what\'s the current value" and "what\'s been measured many times".',
     inputSchema: {
       type: 'object',
       properties: {
         formulation_ids: { type: 'array', items: { type: 'string' }, description: 'Restrict to specific formulation ids/UIDs.' },
         parameter_filter: { type: 'string', description: 'Case-insensitive substring; restrict parameter columns.' },
+        grain: { type: 'string', enum: ['formulation', 'batch', 'sample'], description: 'Row level. Default formulation.' },
         format: { type: 'string', enum: ['csv', 'json'], description: 'Output format. Default csv.' },
       },
     },
@@ -498,38 +633,77 @@ const get_coverage_matrix = {
       const ids = args.formulation_ids.map(i => resolveById('formulations', i)?.id).filter(Boolean);
       allowed = new Set(ids);
     }
-    const counts = new Map(); // formId -> Map(param -> count)
-    (db.testResults || []).forEach(t => {
-      if (!t || t._trashed) return;
+    const grain = ['batch', 'sample'].includes(args.grain) ? args.grain : 'formulation';
+    const tests = (db.testResults || []).filter(t => {
+      if (!t || t._trashed) return false;
+      if (!allowed) return true;
       const samp = indexes.samplesById.get(t.sampleId);
-      const formId = samp?.formulationId;
-      if (!formId) return;
-      if (allowed && !allowed.has(formId)) return;
-      if (!counts.has(formId)) counts.set(formId, new Map());
-      const inner = counts.get(formId);
-      (t.measurements || []).forEach(m => {
-        if (!m || !m.parameter) return;
-        if (args.parameter_filter && !norm(m.parameter).includes(norm(args.parameter_filter))) return;
-        inner.set(m.parameter, (inner.get(m.parameter) || 0) + 1);
-      });
-    });
-    const allParams = new Set();
-    counts.forEach(inner => inner.forEach((_, p) => allParams.add(p)));
-    const paramCols = [...allParams].sort();
-    const formRows = [...counts.entries()].map(([fid, inner]) => {
-      const f = indexes.formulationsById.get(fid);
-      return { formulation: f?.name || f?.uid || fid, formulationId: fid, ...Object.fromEntries(paramCols.map(p => [p, inner.get(p) || 0])) };
+      return !!(samp && allowed.has(samp.formulationId));
     });
+    const flat = _mcpFlattenReadings(tests, indexes, args.parameter_filter);
+    const rows = _mcpCoverageRows(flat, grain, indexes);
+    const paramSet = new Set();
+    rows.forEach(r => r.cells.forEach((_, p) => paramSet.add(p)));
+    const paramCols = [...paramSet].sort();
+    const sorted = [...rows.values()].sort((a, b) => String(a.label).localeCompare(String(b.label)));
+    const grainLabel = grain === 'formulation' ? 'Formulation' : grain === 'batch' ? 'Batch' : 'Sample';
     if (fmt === 'json') {
-      return { formulationCount: formRows.length, parameterCount: paramCols.length, parameters: paramCols, rows: formRows };
+      return {
+        grain, rowCount: sorted.length, parameterCount: paramCols.length, parameters: paramCols,
+        rule: 'cell = latest reading by test date; same-date reports averaged (any fail → fail)',
+        rows: sorted.map(r => ({ [grain]: r.label, id: r.uid, cells: Object.fromEntries([...r.cells.entries()].sort()) })),
+      };
     }
-    const esc = (v) => /[",\n\r]/.test(String(v || '')) ? '"' + String(v).replace(/"/g, '""') + '"' : String(v ?? '');
-    const lines = [['Formulation', ...paramCols].map(esc).join(',')];
-    formRows.forEach(r => lines.push([r.formulation, ...paramCols.map(p => r[p])].map(esc).join(',')));
-    return `# Coverage Matrix · ${formRows.length} formulations × ${paramCols.length} parameters\n` + lines.join('\n');
+    const esc = (v) => /[",\n\r]/.test(String(v ?? '')) ? '"' + String(v).replace(/"/g, '""') + '"' : String(v ?? '');
+    const fmtCell = (c) => {
+      if (!c) return '';
+      const v = c.value == null ? '' : (typeof c.value === 'number' ? +c.value.toPrecision(6) : c.value);
+      const bits = [c.latestDate || '?'];
+      if (c.reportsAveraged > 1) bits.push(`avg of ${c.reportsAveraged}`);
+      bits.push(`${c.nReports} report${c.nReports === 1 ? '' : 's'}`);
+      return `${v}${c.unit ? ' ' + c.unit : ''}${c.pf === 'fail' ? ' FAIL' : c.pf === 'pass' ? ' pass' : ''} (${bits.join(', ')})`;
+    };
+    const lines = [[grainLabel, ...paramCols].map(esc).join(',')];
+    sorted.forEach(r => lines.push([r.label, ...paramCols.map(p => fmtCell(r.cells.get(p)))].map(esc).join(',')));
+    return `# Coverage Matrix · ${sorted.length} ${grain === 'batch' ? 'batches' : grain + 's'} × ${paramCols.length} parameters · cell = latest reading (same-day reports averaged)\n` + lines.join('\n');
   },
 };
 
+// Latest-date rollup (mirrors the app's _taCoverageRows).
+function _mcpCoverageRows(flat, grain, indexes) {
+  const rows = new Map();
+  for (const r of flat) {
+    let rec = null, label = '';
+    if (grain === 'sample') { rec = r.sample; label = rec && (rec.uid || rec.id); }
+    else if (grain === 'batch') { rec = r.sample && r.sample.batchId ? indexes.batchesById.get(r.sample.batchId) : null; label = rec && (rec.uid || rec.id); }
+    else { rec = r.formulation; label = rec && (rec.name || rec.uid); }
+    if (!rec) continue;
+    if (!rows.has(rec.id)) rows.set(rec.id, { label: label || rec.id, uid: rec.uid || rec.id, latest: new Map(), reports: new Map() });
+    const row = rows.get(rec.id);
+    const date = String(r.test.testDate || '');
+    if (!row.reports.has(r.parameter)) row.reports.set(r.parameter, new Set());
+    row.reports.get(r.parameter).add(r.test.id || r.test.uid);
+    const cur = row.latest.get(r.parameter);
+    if (!cur || cur.date < date) row.latest.set(r.parameter, { date, list: [r] });
+    else if (cur.date === date) cur.list.push(r);
+  }
+  for (const row of rows.values()) {
+    row.cells = new Map();
+    for (const [param, { date, list }] of row.latest) {
+      const nums = list.map(x => x.numeric).filter(v => v != null && isFinite(v));
+      const mean = nums.length ? nums.reduce((a, b) => a + b, 0) / nums.length : null;
+      const pf = list.some(x => x.pf === 'fail') ? 'fail' : list.some(x => x.pf === 'pass') ? 'pass' : list[0].pf;
+      row.cells.set(param, {
+        value: list.length === 1 ? (list[0].numeric != null ? list[0].numeric : list[0].value) : (mean != null ? mean : list[0].value),
+        unit: list[0].unit, pf: (pf === 'pass' || pf === 'fail') ? pf : null,
+        latestDate: date || null, reportsAveraged: list.length, nReports: row.reports.get(param).size,
+      });
+    }
+    delete row.latest; delete row.reports;
+  }
+  return rows;
+}
+
 // ============================================================
 // SAVED DOE DESIGNS
 // ------------------------------------------------------------
@@ -809,7 +983,24 @@ function _shelfLife(points, spec) {
   for (let tt = lastX; tt <= lastX + 120; tt += 0.25) {
     if (fit.slope < 0 ? bound(tt) <= limit : bound(tt) >= limit) { ciRemaining = tt - lastX; break; }
   }
-  return { edge, limit, remainingMonths: remaining, ciRemainingMonths: ciRemaining, r2: fit.r2 };
+  return { edge, limit, remainingMonths: remaining, ciRemainingMonths: ciRemaining, r2: fit.r2, elapsedMonths: lastX };
+}
+
+// Same verdict rule as the app (js/views/stability.js stabShelfLifeAssess):
+// months from T0 vs the target shelf life — short (trend crosses first),
+// marginal (only the 95% bound does), meets; no target → by time left
+// (<3 mo high, <12 mo medium). Nothing past the 5-year horizon is reported.
+function _shelfLifeAssess(sl, targetMonths) {
+  if (!sl || !(sl.r2 >= 0.3) || !(sl.remainingMonths > 0.05)) return null;
+  const pointTotal = sl.elapsedMonths + sl.remainingMonths;
+  const ciTotal = sl.ciRemainingMonths != null ? sl.elapsedMonths + sl.ciRemainingMonths : null;
+  if (targetMonths) {
+    const verdict = pointTotal < targetMonths ? 'short' : (ciTotal != null && ciTotal < targetMonths) ? 'marginal' : 'meets';
+    if (verdict === 'meets' && sl.remainingMonths > 60) return null;
+    return { verdict, level: verdict === 'short' ? 'high' : verdict === 'marginal' ? 'medium' : 'info', pointTotal, ciTotal };
+  }
+  if (sl.remainingMonths > 60) return null;
+  return { verdict: null, level: sl.remainingMonths < 3 ? 'high' : sl.remainingMonths < 12 ? 'medium' : 'info', pointTotal, ciTotal };
 }
 
 const get_stability = {
@@ -855,7 +1046,7 @@ const get_stability = {
         }
         if (!Number.isFinite(value)) return;
         if (m.unit && !unit) unit = m.unit;
-        const ac = m.acceptanceCriteria;
+        const ac = _resolveSpec(m, t.templateId).spec;
         if (ac) { if (Number.isFinite(ac.min)) specMin = specMin == null ? ac.min : Math.max(specMin, ac.min); if (Number.isFinite(ac.max)) specMax = specMax == null ? ac.max : Math.min(specMax, ac.max); }
         const cond = (m.conditions && Object.keys(m.conditions).length)
           ? Object.entries(m.conditions).map(([k, v]) => `${k} ${v}`).join(' · ') : '';
@@ -871,6 +1062,14 @@ const get_stability = {
     if (!points.length) return { error: `No dated "${args.parameter}" measurements on ${entity.uid || entity.id}.` };
 
     const spec = { min: specMin, max: specMax };
+    // Target shelf life: the formula's own Shelf life, else the workspace
+    // default when this store carries it (the app's Settings → Stability).
+    const formula = entityType === 'formulation' ? entity
+      : (db.formulations || []).find(f => f.id === entity.formulationId) || null;
+    const ownT = formula ? parseFloat(formula.shelfLifeMonths) : NaN;
+    const defT = parseFloat(db.defaultShelfLifeMonths);
+    const target = (Number.isFinite(ownT) && ownT > 0) ? { months: ownT, source: 'formula' }
+      : (Number.isFinite(defT) && defT > 0) ? { months: defT, source: 'workspace default' } : null;
     const analyze = (pts) => {
       const ys = pts.map(p => p.value);
       const n = ys.length;
@@ -886,11 +1085,17 @@ const get_stability = {
       if (ic) out.controlChart = { mean: _round(ic.mean), ucl: _round(ic.ucl), lcl: _round(ic.lcl), sigma: _round(ic.sigma), outOfControlPoints: ic.ooc };
       if (spec.min != null || spec.max != null) out.spec = { ...spec, latestInSpec: (spec.min == null || ys[n - 1] >= spec.min) && (spec.max == null || ys[n - 1] <= spec.max) };
       const sl = _shelfLife(pts, spec);
+      const as = _shelfLifeAssess(sl, target && target.months);
       if (sl) out.shelfLife = {
         headingToward: `${sl.edge} spec (${_round(sl.limit)})`,
         remainingMonths: _round(sl.remainingMonths, 1),
         ci95Months: sl.ciRemainingMonths != null ? _round(sl.ciRemainingMonths, 1) : null,
+        fromT0Months: _round(sl.elapsedMonths + sl.remainingMonths, 1),
+        ci95FromT0Months: sl.ciRemainingMonths != null ? _round(sl.elapsedMonths + sl.ciRemainingMonths, 1) : null,
         r2: _round(sl.r2, 2), basis: 'linear extrapolation to spec crossing',
+        verdict: as ? as.verdict : null,
+        concern: as ? as.level : null,
+        reportable: !!as,
       };
       return out;
     };
@@ -908,12 +1113,13 @@ const get_stability = {
     return {
       entity: { type: entityType, uid: entity.uid, name: entity.name || entity.uid },
       parameter: args.parameter, unit, spec, pointCount: points.length, byCondition: split, series,
-      note: 'shelfLife.remainingMonths is the point-estimate months from the last test to the spec crossing; ci95Months is the conservative (ICH-style) estimate where the 95% confidence bound crosses spec. Numbers are computed here — narrate them, do not recompute.',
+      targetShelfLife: target ? { months: target.months, source: target.source } : null,
+      note: 'shelfLife.fromT0Months / ci95FromT0Months are the projected shelf life counted from the first test (T0): point estimate and the conservative (ICH Q1E) 95%-bound crossing. remainingMonths / ci95Months are the same, counted from the last test. verdict compares against targetShelfLife: "short" = the trend crosses spec before the target, "marginal" = the trend clears it but the 95% bound does not, "meets" = both clear it; null = no target set (then concern is by time left: high <3 mo, medium <12 mo). reportable=false means the app shows no projection (R² < 0.3, crossing already past, or beyond 5 years). Numbers are computed here — narrate them, do not recompute.',
     };
   },
 };
 
-export { _evalPassFail };
+export { _evalPassFail, _resolveSpec, _shelfLife, _shelfLifeAssess };
 export const tools = {
   list_test_results,
   get_test_result,

package/tools/documents.js

@@ -0,0 +1,165 @@
+// =====================================================================
+// DOCUMENTS — list_documents. Mirrors the app's Documents page
+// (js/views/documents-library.js): one register of every uploaded file —
+// ingredient SDS / PDS / CoA / other, test-result attachments, notebook
+// attachments, and per-record uploads + links (record.fileAttachments[] on
+// formulas, batches, samples, suppliers, equipment…). Metadata only: the
+// file bytes are never read, so this cannot search the text inside a PDF.
+// The summary block carries the same counts as the page's quick-filter tiles.
+// =====================================================================
+import { getStore } from '../data.js';
+import { _lotCoaInfo } from './ingredients.js';
+
+const DAY = 86400000;
+const RECENT_DAYS = 7;
+const SOON_DAYS = 30;
+const live = (x) => x && !x._trashed && !x.deletedAt;
+const norm = (s) => String(s == null ? '' : s).trim().toLowerCase();
+
+// record.fileAttachments[] live on these collections (app: _ATTACH_ENTITY_COLL).
+const ATTACH_COLL = {
+  formulation: 'formulations', ingredient: 'ingredients', batch: 'batches', sample: 'samples',
+  test: 'testResults', project: 'projects', template: 'templates', procedureTemplate: 'procedureTemplates',
+  parameter: 'parameters', equipment: 'equipment', supplier: 'suppliers',
+};
+const NOTE_COLL = {
+  ingredient: 'ingredients', formulation: 'formulations', batch: 'batches', sample: 'samples', project: 'projects',
+  test: 'testResults', testResult: 'testResults', template: 'templates', parameter: 'parameters', equipment: 'equipment',
+};
+
+// App: docExpiryStatus — date-only, local midnight; <0 expired, ≤30 soon.
+function expiryInfo(doc, today) {
+  if (!doc || !doc.expiryDate) return { status: 'none', daysToExpiry: null };
+  const exp = new Date(String(doc.expiryDate).slice(0, 10) + 'T00:00:00');
+  if (isNaN(exp.getTime())) return { status: 'none', daysToExpiry: null };
+  const days = Math.round((exp - today) / DAY);
+  return { status: days < 0 ? 'expired' : days <= SOON_DAYS ? 'soon' : 'current', daysToExpiry: days };
+}
+function formatOf(name, mime, isLink) {
+  if (isLink) return 'link';
+  const m = norm(mime);
+  const ext = (String(name || '').split('.').pop() || '').toLowerCase();
+  if (m.startsWith('image/') || /^(jpe?g|png|gif|webp|bmp|svg|heic|tiff?)$/.test(ext)) return 'image';
+  if (m === 'application/pdf' || ext === 'pdf') return 'pdf';
+  return 'other';
+}
+
+function allDocuments(db) {
+  const out = [];
+  const today = new Date(); today.setHours(0, 0, 0, 0);
+  const push = (row) => {
+    const up = row.uploadedAt ? Date.parse(row.uploadedAt) : NaN;
+    out.push({ ...row, ageDays: isFinite(up) ? Math.floor((Date.now() - up) / DAY) : null });
+  };
+  (db.ingredients || []).filter(live).forEach(ing => (ing.documents || []).forEach(d => {
+    if (!d) return;
+    const ex = expiryInfo(d, today);
+    push({
+      type: String(d.docType || 'OTHER').toUpperCase(), name: d.filename || '', format: formatOf(d.filename, d.type, false),
+      record: 'ingredient', linked: ing.name || ing.uid || '', linkedId: ing.uid || ing.id,
+      lot: d.lotNumber || '', version: d.version != null ? String(d.version) : '', source: d.source || '',
+      expiryDate: d.expiryDate || null, expiryStatus: ex.status, daysToExpiry: ex.daysToExpiry,
+      sizeKb: Number.isFinite(+d.size) && d.size != null ? Math.round(+d.size / 102.4) / 10 : null,
+      uploadedAt: d.uploadedAt || null,
+    });
+  }));
+  const testsById = new Map((db.testResults || []).map(t => [t.id, t]));
+  (db.attachments || []).filter(live).forEach(a => {
+    const t = testsById.get(a.testResultId);
+    push({
+      type: 'TEST', name: a.fileName || '', format: formatOf(a.fileName, a.fileType || a.mime, false),
+      record: 'test', linked: (t ? (t.uid || t.id) : 'Test') + (a.measurementParameter ? ' · ' + a.measurementParameter : ''), linkedId: t ? (t.uid || t.id) : null,
+      lot: '', version: '', source: '', expiryDate: null, expiryStatus: 'none', daysToExpiry: null,
+      sizeKb: Number.isFinite(+a.fileSize) && a.fileSize != null ? Math.round(+a.fileSize / 102.4) / 10 : null,
+      uploadedAt: a.uploadedAt || null,
+    });
+  });
+  (db.notebookEntries || []).filter(live).forEach(ne => (ne.attachments || []).forEach(att => {
+    if (!att) return;
+    const coll = NOTE_COLL[ne.entityType];
+    const rec = coll ? (db[coll] || []).find(x => x && x.id === ne.entityId) : null;
+    push({
+      type: 'NOTE', name: att.filename || '', format: formatOf(att.filename, att.type, false),
+      record: 'notebook', linked: rec ? (rec.name || rec.uid || '') : (ne.entityType || 'note'), linkedId: rec ? (rec.uid || rec.id) : null,
+      lot: '', version: '', source: '', expiryDate: null, expiryStatus: 'none', daysToExpiry: null,
+      sizeKb: Number.isFinite(+att.size) && att.size != null ? Math.round(+att.size / 102.4) / 10 : null,
+      uploadedAt: att.uploadedAt || null,
+    });
+  }));
+  Object.entries(ATTACH_COLL).forEach(([etype, coll]) => (db[coll] || []).filter(live).forEach(rec => (rec.fileAttachments || []).forEach(a => {
+    if (!a) return;
+    const isLink = a.kind === 'link';
+    push({
+      type: isLink ? 'LINK' : 'FILE', name: a.name || '', format: formatOf(a.name, a.mime, isLink),
+      record: etype, linked: rec.name || rec.uid || '', linkedId: rec.uid || rec.id,
+      ...(isLink && a.url ? { url: a.url } : {}),
+      lot: '', version: '', source: '', expiryDate: null, expiryStatus: 'none', daysToExpiry: null,
+      sizeKb: (!isLink && Number.isFinite(+a.size) && a.size != null) ? Math.round(+a.size / 102.4) / 10 : null,
+      uploadedAt: a.createdAt || null,
+    });
+  })));
+  return out;
+}
+
+function summary(db, docs) {
+  const ings = (db.ingredients || []).filter(live);
+  const missingSds = ings.filter(i => !(i.documents || []).some(d => d && d.docType === 'SDS'));
+  const ingById = new Map(ings.map(i => [i.id, i]));
+  const lotsWithoutCoa = (db.lots || []).filter(l => live(l) && _lotCoaInfo(l, ingById.get(l.ingredientId)).coaMissing);
+  return {
+    files: docs.length,
+    expired: docs.filter(d => d.expiryStatus === 'expired').length,
+    expiringIn30Days: docs.filter(d => d.expiryStatus === 'soon').length,
+    sdsOrCoaWithoutExpiry: docs.filter(d => d.record === 'ingredient' && d.expiryStatus === 'none' && (d.type === 'SDS' || d.type === 'COA')).length,
+    ingredientsMissingSds: missingSds.length,
+    sdsCoveragePct: ings.length ? Math.round(((ings.length - missingSds.length) / ings.length) * 100) : 100,
+    lotsInStockWithoutCoa: lotsWithoutCoa.length,
+    addedLast7Days: docs.filter(d => d.ageDays != null && d.ageDays <= RECENT_DAYS).length,
+  };
+}
+
+const list_documents = {
+  definition: {
+    name: 'list_documents',
+    description: 'The workspace document register — same list as the app\'s Documents page: ingredient SDS / PDS / CoA / other files (with lot, version, source, expiry), test-result and notebook attachments, and per-record uploads and links (formulas, batches, samples, suppliers, equipment…). Returns file METADATA only (never the text inside a file). Filters combine. The summary block matches the page\'s tiles: expired, expiring in 30 days, SDS/CoA without an expiry date, ingredients missing an SDS (+ coverage %), lots in stock without a CoA, files added in the last 7 days. For the lots themselves use list_lots with missing_coa: true.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        type: { type: 'array', items: { type: 'string' }, description: 'Document types to include: SDS, PDS, COA, OTHER (ingredient documents), TEST, NOTE, FILE (upload), LINK.' },
+        record: { type: 'string', description: 'Kind of record the file is attached to: ingredient, formulation, batch, sample, test, notebook, project, supplier, equipment, template, procedureTemplate, parameter.' },
+        linked: { type: 'string', description: 'Case-insensitive substring of the linked record\'s name / UID.' },
+        query: { type: 'string', description: 'Case-insensitive substring over file name, linked record, lot and source.' },
+        lot: { type: 'string', description: 'Exact lot number (case-insensitive).' },
+        format: { type: 'string', enum: ['pdf', 'image', 'link', 'other'], description: 'File format.' },
+        expiry: { type: 'string', enum: ['expired', 'soon', 'current', 'none'], description: 'Expiry status (ingredient documents only; soon = within 30 days).' },
+        expiring_within_days: { type: 'number', description: 'Only documents whose expiry date is within this many days (already expired included).' },
+        without_expiry: { type: 'boolean', description: 'true = only SDS / CoA files with no expiry date (the "SDS / CoA without expiry" tile).' },
+        uploaded_within_days: { type: 'number', description: 'Only files uploaded within this many days.' },
+        limit: { type: 'number', description: 'Max rows (default 200, max 1000).' },
+      },
+    },
+  },
+  handler: async (args) => {
+    const { db } = getStore();
+    const all = allDocuments(db);
+    const limit = Math.min(1000, Math.max(1, args.limit || 200));
+    const types = Array.isArray(args.type) ? new Set(args.type.map(t => String(t).toUpperCase())) : (args.type ? new Set([String(args.type).toUpperCase()]) : null);
+    const q = norm(args.query), linkedQ = norm(args.linked);
+    const rows = all.filter(d => {
+      if (types && !types.has(d.type)) return false;
+      if (args.record && norm(d.record) !== norm(args.record)) return false;
+      if (linkedQ && !(norm(d.linked).includes(linkedQ) || norm(d.linkedId).includes(linkedQ))) return false;
+      if (q && ![d.name, d.linked, d.lot, d.source].some(v => norm(v).includes(q))) return false;
+      if (args.lot && norm(d.lot) !== norm(args.lot)) return false;
+      if (args.format && d.format !== args.format) return false;
+      if (args.expiry && d.expiryStatus !== args.expiry) return false;
+      if (args.expiring_within_days != null && !(d.daysToExpiry != null && d.daysToExpiry <= args.expiring_within_days)) return false;
+      if (args.without_expiry === true && !(d.record === 'ingredient' && d.expiryStatus === 'none' && (d.type === 'SDS' || d.type === 'COA'))) return false;
+      if (args.uploaded_within_days != null && !(d.ageDays != null && d.ageDays <= args.uploaded_within_days)) return false;
+      return true;
+    }).sort((a, b) => String(b.uploadedAt || '').localeCompare(String(a.uploadedAt || '')));
+    return { summary: summary(db, all), totalMatching: rows.length, returned: Math.min(rows.length, limit), documents: rows.slice(0, limit) };
+  },
+};
+
+export const tools = { list_documents };

package/tools/formulations.js

@@ -22,6 +22,8 @@ function _trimFormulation(f) {
     application: f.application || '',
     owner: f.owner || '',
     regulatoryCategory: f.regulatoryCategory || '',
+    // Target shelf life (months): sets finished-goods expiry AND is what
+    // get_stability judges the projected shelf life against.
     shelfLifeMonths: f.shelfLifeMonths ?? null,
     // Density of the MIXED product (g/mL), when declared — volume-targeted
     // batches scale by it instead of the ideal-mix estimate. null = not set.

package/tools/ingredients.js

@@ -5,6 +5,7 @@
 // ============================================================
 
 import { getStore, resolveById } from '../data.js';
+import { ingredientSmiles } from '../peptide.js';
 
 // FormLab's export is the raw db, so ingredients carry the APP field shapes:
 // `cas` (not casNumber) and `cost = {value, currency, unit}` (not a flat
@@ -86,6 +87,22 @@ function _trimIngredient(i) {
   };
 }
 
+// Certificate of Analysis for a lot — mirrors the app's lotsMissingCoa
+// (js/inventory-lots.js): covered when lot.coaDocId points at a COA document
+// still on the ingredient, or (unlinked) when a COA on the ingredient carries
+// the same lot number. coaMissing flags an IN-STOCK (remaining > 0), non-
+// rejected lot with neither — the Documents page "Lots in stock without CoA".
+function _lotCoaInfo(l, ing) {
+  const norm = v => String(v == null ? '' : v).trim().toLowerCase();
+  const coas = ((ing && ing.documents) || []).filter(d => d && d.docType === 'COA');
+  let doc = l.coaDocId ? coas.find(d => d.id === l.coaDocId) : null;
+  let how = doc ? 'linked' : null;
+  if (!doc && norm(l.lotNumber)) { doc = coas.find(d => norm(d.lotNumber) === norm(l.lotNumber)) || null; if (doc) how = 'lot-number match'; }
+  const rem = Number(l.qtyRemaining);
+  const inStock = isFinite(rem) && rem > 0 && l.status !== 'rejected';
+  return { coa: doc ? { file: doc.filename || '', match: how, expiryDate: doc.expiryDate || null } : null, coaMissing: inStock && !doc };
+}
+
 // Resolve the approved source a lot was received from (lot.sourceId → the
 // ingredient's ing.sources[]). Null when the lot predates sources or is unlinked.
 function _lotSourceInfo(l) {
@@ -200,6 +217,7 @@ const get_ingredient = {
         receivedDate: l.receivedDate || null, expiryDate: l.expiryDate || null,
         supplier: l.supplier || '', supplierId: l.supplierId || null, status: l.status || 'active',
         sourceId: l.sourceId || null, source: _lotSourceInfo(l),
+        ..._lotCoaInfo(l, ing),
       }));
     return {
       ..._trimIngredient(ing),
@@ -249,7 +267,7 @@ async function _loadRDKitNode() {
 const find_by_smarts = {
   definition: {
     name: 'find_by_smarts',
-    description: 'Find every ingredient whose SMILES contains the given SMARTS substructure pattern. Requires RDKit-JS (optional dependency); install with `npm install @rdkit/rdkit` in the mcp folder if you get a "not installed" error.',
+    description: 'Find every ingredient whose SMILES contains the given SMARTS substructure pattern. Peptides with only a sequence are searched with the structure derived from it (as the app draws them); those rows carry smilesDerived: true. Requires RDKit-JS (optional dependency); install with `npm install @rdkit/rdkit` in the mcp folder if you get a "not installed" error.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -272,7 +290,8 @@ const find_by_smarts = {
         underlying: e?.message || String(e),
       };
     }
-    const candidates = (db.ingredients || []).filter(i => i && !i._trashed && i.smiles);
+    const candidates = (db.ingredients || []).filter(i => i && !i._trashed)
+      .map(i => ({ ing: i, ...ingredientSmiles(i) })).filter(c => c.smiles);
     const matches = [];
     let invalid = 0;
     const limit = Math.min(1000, Math.max(1, args.limit || 100));
@@ -280,8 +299,8 @@ const find_by_smarts = {
     const query = rdkit.get_qmol(smarts);
     if (!query) return { error: `Invalid SMARTS: "${smarts}"` };
     try {
-      for (const ing of candidates) {
-        const mol = rdkit.get_mol(ing.smiles);
+      for (const { ing, smiles, derived } of candidates) {
+        const mol = rdkit.get_mol(smiles);
         if (!mol) { invalid++; continue; }
         try {
           const raw = mol.get_substruct_match(query);
@@ -289,7 +308,7 @@ const find_by_smarts = {
             try {
               const parsed = JSON.parse(raw);
               if (Array.isArray(parsed.atoms) && parsed.atoms.length > 0) {
-                matches.push(_trimIngredient(ing));
+                matches.push(derived ? { ..._trimIngredient(ing), smilesDerived: true } : _trimIngredient(ing));
                 if (matches.length >= limit) break;
               }
             } catch { /* skip parse fail */ }
@@ -326,6 +345,7 @@ const list_lots = {
         ingredient_id: { type: 'string', description: 'Only lots for this ingredient (internal id or UID, e.g. ING-001).' },
         expiring_within_days: { type: 'number', description: 'Only lots whose expiryDate is within this many days from now (negative days = already expired are always included).' },
         status: { type: 'string', description: 'Filter by lot status: "active", "hold", "quarantine", or "rejected". Held/quarantined/rejected lots are blocked from auto-consumption (use "hold" to find lots put on hold for a QC / recall).' },
+        missing_coa: { type: 'boolean', description: 'true = only lots still in stock (not rejected) that have no Certificate of Analysis — neither linked nor a CoA on the ingredient with the same lot number. Same list as the app\'s Documents → "Lots in stock without CoA".' },
         limit: { type: 'number', description: 'Max rows (default 200, max 1000).' },
       },
     },
@@ -339,10 +359,12 @@ const list_lots = {
       if (!ing) return { error: `No ingredient found for id "${args.ingredient_id}".` };
     }
     const nameById = new Map((db.ingredients || []).map(i => [i.id, i.name]));
+    const ingById = new Map((db.ingredients || []).map(i => [i.id, i]));
     const nowMs = Date.now();
     const rows = (db.lots || []).filter(l => {
       if (!l || l._trashed) return false;
       if (ing && l.ingredientId !== ing.id) return false;
+      if (args.missing_coa === true && !_lotCoaInfo(l, ingById.get(l.ingredientId)).coaMissing) return false;
       if (args.status && String(l.status || 'active').toLowerCase() !== String(args.status).toLowerCase()) return false;
       if (args.expiring_within_days != null) {
         if (!l.expiryDate) return false;
@@ -365,6 +387,7 @@ const list_lots = {
       holdReason: l.holdReason || '',
       unitCost: (l.unitCost != null && l.unitCost !== '') ? l.unitCost : null,
       unitCostCcy: l.unitCostCcy || null,
+      ..._lotCoaInfo(l, ingById.get(l.ingredientId)),
     }));
     return { totalMatching: rows.length, returned: Math.min(rows.length, limit), lots: rows.slice(0, limit) };
   },
@@ -450,4 +473,4 @@ const list_inventory = {
 export const tools = { list_ingredients, get_ingredient, find_by_smarts, list_lots, list_inventory };
 
 // Exported for the batch-analyze tools (avg cost metric) to reuse the same cost normalization.
-export { _costPerKg, _densityKgPerL };
+export { _costPerKg, _densityKgPerL, _lotCoaInfo };

package/tools/library.js

@@ -48,7 +48,7 @@ function _usageRollup(db, tests, measFilter) {
     let tf = 0;
     (t.measurements || []).filter(m => !measFilter || measFilter(m, t)).forEach(m => {
       readings++;
-      const pf = _evalPassFail(m); if (pf !== 'no-criteria' && pf !== 'untested') withSpec++; if (pf === 'fail') { fails++; tf++; }
+      const pf = _evalPassFail(m, t.templateId); if (pf !== 'no-criteria' && pf !== 'untested') withSpec++; if (pf === 'fail') { fails++; tf++; }
     });
     const key = f ? f.id : '(no formula)';
     if (!byF.has(key)) byF.set(key, { formula: f ? (f.uid || f.name) : null, formulaName: f ? f.name : null, reports: 0, lastRun: '', fails: 0 });
@@ -168,7 +168,7 @@ const get_equipment = {
       const pn = (m.parameter || '').trim(); if (!pn) return;
       const v = _num(m); const isMine = mine(m, t); const bucket = isMine ? here : fleet;
       if (!bucket.has(pn)) bucket.set(pn, { parameter: pn, readings: 0, vals: [], fails: 0 });
-      const g = bucket.get(pn); g.readings++; if (v != null) g.vals.push(v); if (isMine && _evalPassFail(m) === 'fail') g.fails++;
+      const g = bucket.get(pn); g.readings++; if (v != null) g.vals.push(v); if (isMine && _evalPassFail(m, t.templateId) === 'fail') g.fails++;
     }));
     const measured = [...here.values()].map(g => {
       const f = fleet.get(g.parameter); const mh = _mean(g.vals), me = f ? _mean(f.vals) : null;
@@ -283,7 +283,7 @@ const get_test_method = {
       const v = _num(m); if (v != null) vals.push(v);
       const inst = _resolveInstrument(m, r, db); const key = inst.name || inst.equipmentId || '(unresolved)';
       if (!byInst.has(key)) byInst.set(key, { instrument: key, readings: 0, vals: [], fails: 0 });
-      const g = byInst.get(key); g.readings++; if (v != null) g.vals.push(v); if (_evalPassFail(m) === 'fail') g.fails++;
+      const g = byInst.get(key); g.readings++; if (v != null) g.vals.push(v); if (_evalPassFail(m, r.templateId) === 'fail') g.fails++;
     }));
     const byInstrument = [...byInst.values()].map(g => ({ instrument: g.instrument, readings: g.readings, mean: _r(_mean(g.vals)), fails: g.fails })).sort((a, b) => b.readings - a.readings);
     const valueSummary = { readings: vals.length, mean: _r(_mean(vals)), sd: _r(_sd(vals)), min: vals.length ? Math.min(...vals) : null, max: vals.length ? Math.max(...vals) : null, unit: p.defaultUnit || '' };
@@ -454,7 +454,7 @@ const get_test_panel = {
       tests.forEach(r => (r.measurements || []).forEach(m => {
         const hit = (pid && m.parameterId === pid) || ((!m.parameterId || !pid) && _norm(m.parameter) === nm);
         if (!hit) return; n++;
-        const pf = _evalPassFail(m); if (pf !== 'no-criteria' && pf !== 'untested') withSpec++; if (pf === 'fail') fails++;
+        const pf = _evalPassFail(m, r.templateId); if (pf !== 'no-criteria' && pf !== 'untested') withSpec++; if (pf === 'fail') fails++;
       }));
       return { parameter: row.parameter || row.name, readings: n, fails, failRatePct: withSpec ? _r(100 * fails / withSpec, 0) : null };
     });